agentra 0.1.0__py3-none-any.whl

agentra/__init__.py

@@ -0,0 +1,3 @@
+"""Agentra — Enterprise AI Engineering Control Plane."""
+
+__version__ = "0.1.0"

agentra/adapters/agents.py

@@ -0,0 +1,231 @@
+"""Agent Integration Adapters — generate optimized configs for each agent platform."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from agentra.models import AgentPlatform, ProjectConfig, StackProfile
+from agentra.governance.engine import GovernanceEngine
+from agentra.optimizer.engine import TokenOptimizer
+
+
+class AgentAdapter(Protocol):
+    """Protocol for agent-specific output adapters."""
+
+    platform: AgentPlatform
+
+    def generate(
+        self,
+        config: ProjectConfig,
+        stack: StackProfile,
+        governance: GovernanceEngine,
+        optimizer: TokenOptimizer,
+    ) -> dict[str, str]:
+        """Return {filename: content} for this agent platform."""
+        ...
+
+
+# ── Shared helpers ───────────────────────────────────────────────────────────
+
+def _build_header(platform_name: str) -> str:
+    return (
+        f"# Agentra — {platform_name} Instructions\n"
+        f"# Auto-generated. Do not edit manually.\n"
+        f"# Regenerate with: ag init\n\n"
+    )
+
+
+def _build_security_block(governance: GovernanceEngine, optimizer: TokenOptimizer) -> str:
+    instructions = governance.generate_instructions()
+    compressed = optimizer.compress_instructions(instructions)
+    return f"## Security & Governance\n{compressed}\n"
+
+
+def _build_stack_block(stack: StackProfile) -> str:
+    lines = ["## Detected Stack"]
+    for cat, label in [
+        ("languages", "Languages"),
+        ("frameworks", "Frameworks"),
+        ("databases", "Databases"),
+        ("sdks", "SDKs"),
+        ("infrastructure", "Infrastructure"),
+    ]:
+        components = getattr(stack, cat)
+        if components:
+            names = ", ".join(c.name for c in components)
+            lines.append(f"- **{label}**: {names}")
+    return "\n".join(lines) + "\n"
+
+
+def _build_skills_block(config: ProjectConfig) -> str:
+    if not config.skills:
+        return ""
+    lines = ["## Active Skills"]
+    for s in config.skills:
+        lines.append(f"- {s}")
+    return "\n".join(lines) + "\n"
+
+
+# ── Claude Adapter ───────────────────────────────────────────────────────────
+
+class ClaudeAdapter:
+    platform = AgentPlatform.CLAUDE
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        parts = [
+            _build_header("Claude Code (CLAUDE.md)"),
+            _build_stack_block(stack),
+            _build_security_block(governance, optimizer),
+            _build_skills_block(config),
+        ]
+        return {"CLAUDE.md": "\n".join(parts)}
+
+
+# ── Cursor Adapter ───────────────────────────────────────────────────────────
+
+class CursorAdapter:
+    platform = AgentPlatform.CURSOR
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        parts = [
+            _build_header("Cursor (.cursorrules)"),
+            _build_stack_block(stack),
+            _build_security_block(governance, optimizer),
+            _build_skills_block(config),
+        ]
+        return {".cursorrules": "\n".join(parts)}
+
+
+# ── GitHub Copilot Adapter ───────────────────────────────────────────────────
+
+class CopilotAdapter:
+    platform = AgentPlatform.COPILOT
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        parts = [
+            _build_header("GitHub Copilot"),
+            _build_stack_block(stack),
+            _build_security_block(governance, optimizer),
+            _build_skills_block(config),
+        ]
+        return {".github/copilot-instructions.md": "\n".join(parts)}
+
+
+# ── Aider Adapter ────────────────────────────────────────────────────────────
+
+class AiderAdapter:
+    platform = AgentPlatform.AIDER
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        parts = [
+            _build_header("Aider (.aider.conf.yml)"),
+            _build_stack_block(stack),
+            _build_security_block(governance, optimizer),
+        ]
+        content = "\n".join(parts)
+        # Wrap in YAML conventions block
+        yaml_content = f"# Aider conventions\nconventions: |\n"
+        for line in content.splitlines():
+            yaml_content += f"  {line}\n"
+        return {".aider.conf.yml": yaml_content}
+
+
+# ── Windsurf Adapter ─────────────────────────────────────────────────────────
+
+class WindsurfAdapter:
+    platform = AgentPlatform.WINDSURF
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        parts = [
+            _build_header("Windsurf"),
+            _build_stack_block(stack),
+            _build_security_block(governance, optimizer),
+            _build_skills_block(config),
+        ]
+        return {".windsurfrules": "\n".join(parts)}
+
+
+# ── Continue.dev Adapter ─────────────────────────────────────────────────────
+
+class ContinueAdapter:
+    platform = AgentPlatform.CONTINUE
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        import json
+        instructions = governance.generate_instructions()
+        compressed = optimizer.compress_instructions(instructions)
+        cfg = {
+            "systemMessage": compressed[:4000],
+            "models": [],
+        }
+        return {".continue/config.json": json.dumps(cfg, indent=2)}
+
+
+# ── AGENTS.md Adapter (universal) ────────────────────────────────────────────
+
+class AgentsMdAdapter:
+    platform = AgentPlatform.CLAUDE  # generic
+
+    def generate(self, config: ProjectConfig, stack: StackProfile,
+                 governance: GovernanceEngine, optimizer: TokenOptimizer) -> dict[str, str]:
+        parts = [
+            _build_header("AGENTS.md — Universal Agent Instructions"),
+            _build_stack_block(stack),
+            _build_security_block(governance, optimizer),
+            _build_skills_block(config),
+            "\n## Execution Safety\n"
+            "- Always dry-run destructive commands first\n"
+            "- Never execute code that modifies production data without approval\n"
+            "- Sandbox all generated code execution\n"
+            "- Create rollback scripts before schema changes\n",
+        ]
+        return {"AGENTS.md": "\n".join(parts)}
+
+
+# ── Registry ─────────────────────────────────────────────────────────────────
+
+ADAPTER_REGISTRY: dict[AgentPlatform, AgentAdapter] = {
+    AgentPlatform.CLAUDE: ClaudeAdapter(),
+    AgentPlatform.CURSOR: CursorAdapter(),
+    AgentPlatform.COPILOT: CopilotAdapter(),
+    AgentPlatform.AIDER: AiderAdapter(),
+    AgentPlatform.WINDSURF: WindsurfAdapter(),
+    AgentPlatform.CONTINUE: ContinueAdapter(),
+}
+
+
+def generate_for_agents(
+    agents: list[AgentPlatform],
+    config: ProjectConfig,
+    stack: StackProfile,
+    governance: GovernanceEngine,
+    optimizer: TokenOptimizer,
+) -> dict[str, str]:
+    """Generate config files for all requested agents. Returns {path: content}."""
+    outputs: dict[str, str] = {}
+    for agent in agents:
+        adapter = ADAPTER_REGISTRY.get(agent)
+        if adapter:
+            outputs.update(adapter.generate(config, stack, governance, optimizer))
+    # Always include AGENTS.md
+    agents_adapter = AgentsMdAdapter()
+    outputs.update(agents_adapter.generate(config, stack, governance, optimizer))
+    return outputs
+
+
+def write_agent_files(output_dir: Path, files: dict[str, str]) -> list[Path]:
+    """Write generated agent files to disk."""
+    written: list[Path] = []
+    for rel_path, content in files.items():
+        fp = output_dir / rel_path
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content, encoding="utf-8")
+        written.append(fp)
+    return written

agentra/benchmarks/runner.py

@@ -0,0 +1,243 @@
+"""Benchmark Runner — measures before/after metrics for each skill."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from agentra.models import (
+    BenchmarkMetric,
+    BenchmarkReport,
+    OptimizationResult,
+    SkillBenchmark,
+)
+from agentra.detection.engine import StackDetector
+from agentra.governance.engine import GovernanceEngine
+from agentra.governance.policies import ALL_POLICIES, get_policies_for_stack
+from agentra.optimizer.engine import TokenOptimizer
+from agentra.skills.registry import BUILTIN_SKILLS, SkillRegistry
+from agentra.compliance.engine import ComplianceEngine
+
+
+class BenchmarkRunner:
+    """Runs before/after benchmarks for each skill to quantify improvement."""
+
+    def __init__(self, project_root: Path | str):
+        self.root = Path(project_root).resolve()
+        self.registry = SkillRegistry()
+
+    def run(self) -> BenchmarkReport:
+        """Execute full benchmark suite."""
+        detector = StackDetector(self.root)
+        stack = detector.detect()
+        stack_names = [c.name for c in stack.all_components] or ["all"]
+
+        # Baseline governance (no skills applied)
+        gov_engine = GovernanceEngine(stack)
+        baseline_result = gov_engine.enforce(self.root)
+
+        # Baseline optimization
+        all_policies = get_policies_for_stack(stack_names)
+        optimizer = TokenOptimizer()
+        baseline_opt = optimizer.optimize(all_policies, stack)
+
+        # Resolve applicable skills
+        applicable_skills = self.registry.resolve_for_stack(stack_names)
+
+        skill_benchmarks: list[SkillBenchmark] = []
+        for skill in applicable_skills:
+            sb = self._benchmark_skill(skill, stack_names, baseline_opt, baseline_result)
+            skill_benchmarks.append(sb)
+
+        # Also benchmark the governance engine itself
+        gov_benchmark = self._benchmark_governance(baseline_result)
+        skill_benchmarks.append(gov_benchmark)
+
+        # Benchmark the optimization engine
+        opt_benchmark = self._benchmark_optimization(baseline_opt)
+        skill_benchmarks.append(opt_benchmark)
+
+        return BenchmarkReport(
+            project_name=self.root.name,
+            stack=stack,
+            governance=baseline_result,
+            optimization=baseline_opt,
+            skill_benchmarks=skill_benchmarks,
+        )
+
+    def _benchmark_skill(
+        self, skill, stack_names: list[str],
+        baseline_opt: OptimizationResult, baseline_result
+    ) -> SkillBenchmark:
+        """Benchmark a single skill: measure token cost, coverage, relevance."""
+        from agentra.optimizer.engine import _estimate_tokens
+
+        metrics: list[BenchmarkMetric] = []
+
+        # ── 1. Token cost of skill instructions ──────────────────────────
+        skill_tokens = _estimate_tokens(skill.instructions) if skill.instructions else 0
+        # Without skill: 0 tokens for this skill, with skill: skill_tokens
+        metrics.append(BenchmarkMetric(
+            name="Instruction Token Cost",
+            before=0,
+            after=skill_tokens,
+            unit="tokens",
+            improvement_pct=0,
+            description=f"Tokens consumed by {skill.name} instructions.",
+        ))
+
+        # ── 2. Policy coverage ───────────────────────────────────────────
+        all_policy_ids = {p.id for p in ALL_POLICIES}
+        skill_policy_ids = set(skill.policies) & all_policy_ids
+        before_coverage = 0
+        after_coverage = len(skill_policy_ids)
+        metrics.append(BenchmarkMetric(
+            name="Security Policy Coverage",
+            before=before_coverage,
+            after=after_coverage,
+            unit="policies",
+            improvement_pct=100.0 if after_coverage > 0 else 0,
+            description=f"Security policies activated by {skill.name}.",
+        ))
+
+        # ── 3. Context relevance score ───────────────────────────────────
+        # Score based on stack match
+        stack_lower = {s.lower() for s in stack_names}
+        skill_stacks = {s.lower() for s in skill.stacks}
+        if "all" in skill_stacks:
+            relevance = 0.8
+        elif skill_stacks & stack_lower:
+            relevance = 1.0
+        else:
+            relevance = 0.2
+
+        metrics.append(BenchmarkMetric(
+            name="Context Relevance",
+            before=0.0,
+            after=round(relevance, 2),
+            unit="score (0-1)",
+            improvement_pct=round(relevance * 100, 1),
+            description=f"How relevant {skill.name} is to the detected stack.",
+        ))
+
+        # ── 4. Instruction compression ratio ────────────────────────────
+        if skill.instructions:
+            raw_lines = len(skill.instructions.splitlines())
+            optimizer = TokenOptimizer()
+            compressed = optimizer.compress_instructions([skill.instructions])
+            compressed_lines = len(compressed.splitlines())
+            ratio = ((raw_lines - compressed_lines) / raw_lines * 100) if raw_lines > 0 else 0
+            metrics.append(BenchmarkMetric(
+                name="Instruction Compression",
+                before=raw_lines,
+                after=compressed_lines,
+                unit="lines",
+                improvement_pct=round(max(0, ratio), 1),
+                description="Compression achieved on skill instructions.",
+            ))
+
+        # ── 5. Verification: does the skill have all required fields? ────
+        verified = bool(
+            skill.instructions
+            and skill.name
+            and skill.description
+            and skill.stacks
+        )
+
+        return SkillBenchmark(
+            skill_id=skill.id,
+            skill_name=skill.name,
+            metrics=metrics,
+            verification_passed=verified,
+            verification_details=(
+                "All required fields present." if verified
+                else "Missing required fields: "
+                + ", ".join(
+                    f for f, v in [
+                        ("instructions", skill.instructions),
+                        ("name", skill.name),
+                        ("description", skill.description),
+                        ("stacks", skill.stacks),
+                    ] if not v
+                )
+            ),
+        )
+
+    def _benchmark_governance(self, result) -> SkillBenchmark:
+        """Benchmark the governance engine itself."""
+        total_policies = len(ALL_POLICIES)
+        violations = len(result.violations)
+
+        metrics = [
+            BenchmarkMetric(
+                name="Total Policies Active",
+                before=0,
+                after=total_policies,
+                unit="policies",
+                improvement_pct=100,
+                description="Number of security policies enforced.",
+            ),
+            BenchmarkMetric(
+                name="Violations Detected",
+                before=0,
+                after=violations,
+                unit="violations",
+                improvement_pct=100 if violations > 0 else 0,
+                description="Policy violations caught by governance engine.",
+            ),
+            BenchmarkMetric(
+                name="Risk Score",
+                before=100,  # Assume worst case without governance
+                after=result.risk_score,
+                unit="score",
+                improvement_pct=round(max(0, (100 - result.risk_score)), 1),
+                description="Risk score (lower is better).",
+            ),
+            BenchmarkMetric(
+                name="Compliance Coverage",
+                before=0,
+                after=len({fw for p in ALL_POLICIES for fw in p.compliance}),
+                unit="frameworks",
+                improvement_pct=100,
+                description="Number of compliance frameworks covered.",
+            ),
+        ]
+
+        return SkillBenchmark(
+            skill_id="governance-engine",
+            skill_name="Security Governance Engine",
+            metrics=metrics,
+            verification_passed=True,
+            verification_details=f"Governance engine operational. {total_policies} policies loaded.",
+        )
+
+    def _benchmark_optimization(self, opt_result: OptimizationResult) -> SkillBenchmark:
+        """Benchmark the token optimization engine."""
+        metrics = [
+            BenchmarkMetric(
+                name="Token Reduction",
+                before=opt_result.original_tokens,
+                after=opt_result.optimized_tokens,
+                unit="tokens",
+                improvement_pct=opt_result.reduction_pct,
+                description="Tokens saved through optimization.",
+            ),
+            BenchmarkMetric(
+                name="Rules Included",
+                before=opt_result.rules_included + opt_result.rules_excluded,
+                after=opt_result.rules_included,
+                unit="rules",
+                improvement_pct=round(
+                    opt_result.rules_excluded / max(1, opt_result.rules_included + opt_result.rules_excluded) * 100, 1
+                ),
+                description="Low-priority rules excluded to save tokens.",
+            ),
+        ]
+
+        return SkillBenchmark(
+            skill_id="optimization-engine",
+            skill_name="Token Optimization Engine",
+            metrics=metrics,
+            verification_passed=True,
+            verification_details=f"Optimization engine operational. {opt_result.reduction_pct:.1f}% token reduction.",
+        )