agent-framework-lib 0.8.6__tar.gz → 0.8.7__tar.gz

{agent_framework_lib-0.8.6/agent_framework_lib.egg-info → agent_framework_lib-0.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.6
+Version: 0.8.7
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>

{agent_framework_lib-0.8.6 → agent_framework_lib-0.8.7}/agent_framework/__init__.py

@@ -32,7 +32,7 @@ Example Usage:
     create_basic_agent_server(MyAgent, port=8000)
     ```
 
-Version: 0.8.6
+Version: 0.8.7
 Author: Cinco AI Team
 License: MIT
 """
@@ -48,22 +48,52 @@ logger = logging.getLogger(__name__)
 
 def _auto_setup_dependencies() -> None:
     """
-    Automatically check and install required dependencies at import time.
+    Check and install required dependencies (Playwright browsers, Deno).
 
-    This runs synchronously when the package is first imported, ensuring
-    Playwright browsers and Deno are available before any async tools try to use them.
+    Behaviour is controlled by ``AGENT_FRAMEWORK_AUTO_SETUP`` (default
+    ``background``):
 
-    Set AGENT_FRAMEWORK_SKIP_AUTO_SETUP=1 to disable this behavior.
+    - ``skip`` / ``0`` / ``false`` / ``no``: do nothing. Dependencies are still
+      installed lazily on first tool use (Playwright) or first MCP run (Deno).
+    - ``background`` (default): run the setup in a daemon thread so importing
+      the package and starting the server are never blocked. The lazy paths
+      remain the safety net if a tool is used before the thread finishes.
+    - ``blocking`` / ``1`` / ``true`` / ``yes``: run synchronously at import
+      time (legacy behaviour).
+
+    ``AGENT_FRAMEWORK_SKIP_AUTO_SETUP`` is still honoured for backward
+    compatibility and forces ``skip``.
     """
+    # Backward-compatible hard skip flag.
     if os.environ.get("AGENT_FRAMEWORK_SKIP_AUTO_SETUP", "").lower() in ("1", "true", "yes"):
         return
 
+    mode = os.environ.get("AGENT_FRAMEWORK_AUTO_SETUP", "background").lower()
+    if mode in ("skip", "0", "false", "no", "off"):
+        return
+
     # Only run once per process
     global _AUTO_SETUP_DONE
     if "_AUTO_SETUP_DONE" in globals() and _AUTO_SETUP_DONE:
         return
     _AUTO_SETUP_DONE = True
 
+    if mode in ("blocking", "1", "true", "yes", "sync"):
+        _run_auto_setup()
+        return
+
+    # Default: run in a background daemon thread so import/startup is not blocked.
+    import threading
+
+    threading.Thread(
+        target=_run_auto_setup,
+        name="agent-framework-auto-setup",
+        daemon=True,
+    ).start()
+
+
+def _run_auto_setup() -> None:
+    """Perform the actual dependency checks/installs (idempotent, cached)."""
     try:
         from .utils.post_install import ensure_deno, ensure_playwright_browsers
 
@@ -89,7 +119,7 @@ def _auto_setup_dependencies() -> None:
 # Track if auto-setup has been done
 _AUTO_SETUP_DONE = False
 
-__version__ = "0.8.6"
+__version__ = "0.8.7"
 __author__ = "Cinco AI Team"
 __license__ = "MIT"
 __email__ = "sebastian@cinco.ai"

agent_framework_lib-0.8.7/agent_framework/code_delivery/__init__.py

@@ -0,0 +1,45 @@
+"""Code-delivery skill — launch coding runs via Herdr and deliver PRs.
+
+This module provides:
+- Domain models (RunState, CodingSpec, CodingRun)
+- Configuration (CodeDeliveryConfig, load_config)
+- Herdr client (HerdrClient)
+- Git provider (GitProvider, GitHubCLIProvider)
+- ES audit logger (CodeDeliveryAuditLogger)
+- Orchestrator (CodeDeliveryOrchestrator)
+- Tool factory (create_code_delivery_tools)
+"""
+
+from agent_framework.code_delivery.audit import CodeDeliveryAuditLogger
+from agent_framework.code_delivery.config import CodeDeliveryConfig, load_config
+from agent_framework.code_delivery.git_provider import (
+    GitHubCLIProvider,
+    GitProvider,
+)
+from agent_framework.code_delivery.herdr_client import HerdrClient
+from agent_framework.code_delivery.models import (
+    CodingRun,
+    CodingSpec,
+    RunState,
+    StateTransition,
+    VALID_TRANSITIONS,
+)
+from agent_framework.code_delivery.orchestrator import CodeDeliveryOrchestrator
+from agent_framework.code_delivery.tools import create_code_delivery_tools
+
+
+__all__ = [
+    "CodeDeliveryAuditLogger",
+    "CodeDeliveryConfig",
+    "CodeDeliveryOrchestrator",
+    "CodingRun",
+    "CodingSpec",
+    "GitHubCLIProvider",
+    "GitProvider",
+    "HerdrClient",
+    "RunState",
+    "StateTransition",
+    "VALID_TRANSITIONS",
+    "create_code_delivery_tools",
+    "load_config",
+]

agent_framework_lib-0.8.7/agent_framework/code_delivery/audit.py

@@ -0,0 +1,371 @@
+"""Elasticsearch audit logger for code-delivery runs.
+
+Provides end-to-end traceability from human request through Herdr actions,
+coding agent work, git operations, and PR delivery.  Every event is indexed
+in a daily-rotated ES index (``code-delivery-runs-{date}``).
+
+If Elasticsearch is unavailable the logger falls back to the Python logging
+system at DEBUG level — the main flow is never blocked or disrupted by audit
+failures.
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from .models import CodingRun, RunState
+
+
+logger = logging.getLogger(__name__)
+
+_INDEX_PREFIX_DEFAULT = "code-delivery-runs"
+
+#: Elasticsearch index mapping for code-delivery audit events.
+_INDEX_MAPPING: dict[str, Any] = {
+    "mappings": {
+        "properties": {
+            # Identity & correlation
+            "run_id": {"type": "keyword"},
+            "event_id": {"type": "keyword"},
+            "event_type": {"type": "keyword"},
+            "timestamp": {"type": "date"},
+            "phase": {"type": "keyword"},
+            # Origin tracing
+            "session_id": {"type": "keyword"},
+            "user_id": {"type": "keyword"},
+            "agent_id": {"type": "keyword"},
+            "correlation_id": {"type": "keyword"},
+            "trace_id": {"type": "keyword"},
+            "span_id": {"type": "keyword"},
+            # Run context
+            "repo_id": {"type": "keyword"},
+            "backend": {"type": "keyword"},
+            "branch_name": {"type": "keyword"},
+            "base_branch": {"type": "keyword"},
+            "pr_url": {"type": "keyword"},
+            # Event payload
+            "detail": {"type": "text"},
+            "spec_snapshot": {"type": "object", "enabled": False},
+            "herdr_request": {"type": "object", "enabled": False},
+            "herdr_response": {"type": "object", "enabled": False},
+            "git_command": {"type": "keyword"},
+            "git_stdout": {"type": "text"},
+            "git_exit_code": {"type": "integer"},
+            "blocked_question": {"type": "text"},
+            "answer_provided": {"type": "text"},
+            "error_message": {"type": "text"},
+            "error_type": {"type": "keyword"},
+            "error_traceback": {"type": "text", "index": False},
+            # Metrics
+            "duration_ms": {"type": "long"},
+            "cumulative_ms": {"type": "long"},
+            "tokens_used": {"type": "object", "enabled": False},
+        }
+    },
+    "settings": {
+        "number_of_shards": 1,
+        "number_of_replicas": 1,
+    },
+}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _get_otel_context() -> tuple[str | None, str | None]:
+    """Extract trace_id and span_id from the current OTel context, if any."""
+    try:
+        from opentelemetry import trace as otel_trace
+
+        span = otel_trace.get_current_span()
+        ctx = span.get_span_context()
+        if ctx and ctx.trace_id:
+            return (
+                format(ctx.trace_id, "032x"),
+                format(ctx.span_id, "016x"),
+            )
+    except Exception:
+        pass
+    return None, None
+
+
+class CodeDeliveryAuditLogger:
+    """Indexes every code-delivery event into Elasticsearch.
+
+    Safe to use even when ES is disabled or unavailable — all public methods
+    swallow exceptions and fall back to Python logging.
+    """
+
+    def __init__(self, index_prefix: str = _INDEX_PREFIX_DEFAULT) -> None:
+        self._index_prefix = index_prefix
+        self._es_client: Any | None = None
+        self._available = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def initialize(self) -> bool:
+        """Create the index template if needed.
+
+        Returns True if ES is available, False otherwise.
+        """
+        try:
+            from agent_framework.session.session_storage import (
+                get_shared_elasticsearch_client,
+            )
+
+            self._es_client = await get_shared_elasticsearch_client()
+            if self._es_client is None:
+                logger.info(
+                    "Elasticsearch not available — code-delivery audit will use Python logging"
+                )
+                self._available = False
+                return False
+
+            # Create today's index if it doesn't exist (idempotent)
+            index_name = self._today_index()
+            exists = await self._es_client.indices.exists(index=index_name)
+            if not exists:
+                await self._es_client.indices.create(
+                    index=index_name, body=_INDEX_MAPPING
+                )
+                logger.info("Created code-delivery audit index: %s", index_name)
+
+            self._available = True
+            return True
+
+        except Exception as exc:
+            logger.warning("Failed to initialize code-delivery audit: %s", exc)
+            self._available = False
+            return False
+
+    # ------------------------------------------------------------------
+    # Core logging
+    # ------------------------------------------------------------------
+
+    async def log_event(
+        self,
+        run: CodingRun,
+        event_type: str,
+        **kwargs: Any,
+    ) -> None:
+        """Log a single audit event.
+
+        Auto-populates run context fields.  Extra kwargs are merged into the
+        document (e.g. ``spec_snapshot``, ``herdr_request``, ``duration_ms``).
+        """
+        trace_id, span_id = _get_otel_context()
+
+        doc: dict[str, Any] = {
+            "run_id": run.run_id,
+            "event_id": str(uuid.uuid4()),
+            "event_type": event_type,
+            "timestamp": _now_iso(),
+            "phase": run.state.value,
+            # Origin tracing
+            "session_id": run.session_id,
+            "user_id": run.user_id,
+            "agent_id": run.agent_id,
+            "correlation_id": run.correlation_id,
+            "trace_id": trace_id,
+            "span_id": span_id,
+            # Run context
+            "repo_id": run.repo_id,
+            "backend": run.backend,
+            "branch_name": run.branch_name,
+            "base_branch": run.spec.base_branch if run.spec else None,
+            "pr_url": run.pr_url,
+        }
+        doc.update(kwargs)
+
+        await self._index(doc, event_type)
+
+    # ------------------------------------------------------------------
+    # Convenience methods
+    # ------------------------------------------------------------------
+
+    async def log_herdr_call(
+        self,
+        run: CodingRun,
+        event_type: str,
+        request: dict[str, Any] | None,
+        response: dict[str, Any] | None,
+        duration_ms: int,
+    ) -> None:
+        """Log a Herdr API call with request/response payloads."""
+        await self.log_event(
+            run,
+            event_type,
+            herdr_request=request,
+            herdr_response=response,
+            duration_ms=duration_ms,
+        )
+
+    async def log_git_call(
+        self,
+        run: CodingRun,
+        event_type: str,
+        command: str,
+        stdout: str,
+        exit_code: int,
+        duration_ms: int,
+    ) -> None:
+        """Log a git/gh CLI call."""
+        await self.log_event(
+            run,
+            event_type,
+            git_command=command,
+            git_stdout=stdout,
+            git_exit_code=exit_code,
+            duration_ms=duration_ms,
+        )
+
+    async def log_transition(
+        self,
+        run: CodingRun,
+        from_state: RunState,
+        to_state: RunState,
+        detail: str | None = None,
+    ) -> None:
+        """Log a state transition."""
+        await self.log_event(
+            run,
+            "transition",
+            detail=detail or f"{from_state.value} -> {to_state.value}",
+        )
+
+    async def log_error(
+        self,
+        run: CodingRun,
+        event_type: str,
+        error: Exception,
+    ) -> None:
+        """Log an error event with exception details."""
+        await self.log_event(
+            run,
+            event_type,
+            error_message=str(error),
+            error_type=type(error).__name__,
+            error_traceback=traceback.format_exc(),
+        )
+
+    # ------------------------------------------------------------------
+    # Query methods
+    # ------------------------------------------------------------------
+
+    async def get_run_timeline(self, run_id: str) -> list[dict[str, Any]]:
+        """Return all events for a run, sorted chronologically."""
+        return await self._search(
+            query={"term": {"run_id": run_id}},
+            sort=[{"timestamp": "asc"}],
+            size=500,
+        )
+
+    async def get_runs_by_session(self, session_id: str) -> list[dict[str, Any]]:
+        """Return events for all runs initiated from a session."""
+        return await self._search(
+            query={"term": {"session_id": session_id}},
+            sort=[{"timestamp": "desc"}],
+            size=200,
+        )
+
+    async def get_runs_by_user(
+        self, user_id: str, limit: int = 50
+    ) -> list[dict[str, Any]]:
+        """Return recent events for runs by a user."""
+        return await self._search(
+            query={"term": {"user_id": user_id}},
+            sort=[{"timestamp": "desc"}],
+            size=limit,
+        )
+
+    async def search_runs(
+        self, query_text: str, limit: int = 20
+    ) -> list[dict[str, Any]]:
+        """Full-text search across detail, questions, errors, and specs."""
+        return await self._search(
+            query={
+                "multi_match": {
+                    "query": query_text,
+                    "fields": [
+                        "detail",
+                        "blocked_question",
+                        "answer_provided",
+                        "error_message",
+                        "git_stdout",
+                    ],
+                }
+            },
+            sort=[{"timestamp": "desc"}],
+            size=limit,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _today_index(self) -> str:
+        date_str = datetime.now(timezone.utc).strftime("%Y.%m.%d")
+        return f"{self._index_prefix}-{date_str}"
+
+    async def _index(self, doc: dict[str, Any], event_type: str) -> None:
+        """Index a document.  Falls back to Python logging on failure."""
+        if self._available and self._es_client:
+            try:
+                await self._es_client.index(
+                    index=self._today_index(),
+                    document=doc,
+                    refresh=False,
+                )
+                return
+            except Exception as exc:
+                logger.debug(
+                    "ES audit index failed (%s), falling back to logging: %s",
+                    event_type,
+                    exc,
+                )
+
+        # Fallback: log the event at DEBUG level
+        logger.debug(
+            "AUDIT [%s] run=%s phase=%s %s",
+            event_type,
+            doc.get("run_id"),
+            doc.get("phase"),
+            {k: v for k, v in doc.items() if v is not None and k not in (
+                "run_id", "event_id", "event_type", "timestamp", "phase",
+                "trace_id", "span_id",
+            )},
+        )
+
+    async def _search(
+        self,
+        query: dict[str, Any],
+        sort: list[dict[str, str]],
+        size: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Execute an ES search.  Returns empty list on any failure."""
+        if not self._available or not self._es_client:
+            return []
+
+        try:
+            resp = await self._es_client.search(
+                index=f"{self._index_prefix}-*",
+                query=query,
+                sort=sort,
+                size=size,
+            )
+            return [hit["_source"] for hit in resp["hits"]["hits"]]
+        except Exception as exc:
+            logger.debug("ES audit search failed: %s", exc)
+            return []
+
+
+__all__ = [
+    "CodeDeliveryAuditLogger",
+]

agent_framework_lib-0.8.7/agent_framework/code_delivery/config.py

@@ -0,0 +1,146 @@
+"""Configuration for the code-delivery skill.
+
+Loads from a YAML file (``.code-delivery.yml``) or falls back to environment
+variables.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+logger = logging.getLogger(__name__)
+
+
+class HerdrConfig(BaseModel):
+    """Connection settings for the Herdr substrate."""
+
+    base_url: str = Field("http://127.0.0.1:9876", description="Herdr API base URL")
+    timeout: float = Field(120.0, description="Default request timeout in seconds")
+
+
+class GitHubConfig(BaseModel):
+    """GitHub provider settings."""
+
+    default_base_branch: str = Field("main", description="Default base branch for PRs")
+    branch_prefix: str = Field("agent/", description="Prefix for run branches")
+    protected_branches: list[str] = Field(
+        default_factory=lambda: ["main", "master", "develop", "release/*"],
+        description="Branch patterns that must never be pushed to",
+    )
+
+
+class BackendConfig(BaseModel):
+    """Coding backend settings."""
+
+    provider: Literal["claude", "codex", "opencode"] = Field(
+        "claude", description="Which coding backend to use"
+    )
+    model: str = Field(
+        "claude-sonnet-4-20250514", description="Model to use in the backend"
+    )
+
+
+class CodeDeliveryConfig(BaseModel):
+    """Top-level code-delivery configuration."""
+
+    herdr: HerdrConfig = Field(default_factory=HerdrConfig)
+    github: GitHubConfig = Field(default_factory=GitHubConfig)
+    backend: BackendConfig = Field(default_factory=BackendConfig)
+    max_concurrent_runs: int = Field(2, description="Max parallel runs")
+    verify_command: str = Field("", description="Gate command (empty = no gate)")
+    retry_on_verify_fail: int = Field(0, description="Retries on verify failure")
+
+
+def _config_from_env() -> dict[str, Any]:
+    """Build a config dict from environment variables."""
+    cfg: dict[str, Any] = {}
+
+    # Herdr
+    herdr: dict[str, Any] = {}
+    if v := os.environ.get("HERDR_BASE_URL"):
+        herdr["base_url"] = v
+    if v := os.environ.get("HERDR_TIMEOUT"):
+        herdr["timeout"] = float(v)
+    if herdr:
+        cfg["herdr"] = herdr
+
+    # GitHub
+    github: dict[str, Any] = {}
+    if v := os.environ.get("CODE_DELIVERY_BASE_BRANCH"):
+        github["default_base_branch"] = v
+    if v := os.environ.get("CODE_DELIVERY_BRANCH_PREFIX"):
+        github["branch_prefix"] = v
+    if v := os.environ.get("CODE_DELIVERY_PROTECTED_BRANCHES"):
+        github["protected_branches"] = [b.strip() for b in v.split(",")]
+    if github:
+        cfg["github"] = github
+
+    # Backend
+    backend: dict[str, Any] = {}
+    if v := os.environ.get("CODE_DELIVERY_BACKEND"):
+        backend["provider"] = v
+    if v := os.environ.get("CODE_DELIVERY_MODEL"):
+        backend["model"] = v
+    if backend:
+        cfg["backend"] = backend
+
+    # Top-level
+    if v := os.environ.get("CODE_DELIVERY_MAX_CONCURRENT"):
+        cfg["max_concurrent_runs"] = int(v)
+    if v := os.environ.get("CODE_DELIVERY_VERIFY_COMMAND"):
+        cfg["verify_command"] = v
+    if v := os.environ.get("CODE_DELIVERY_RETRY_ON_VERIFY_FAIL"):
+        cfg["retry_on_verify_fail"] = int(v)
+
+    return cfg
+
+
+def load_config(path: Path | None = None) -> CodeDeliveryConfig:
+    """Load code-delivery configuration.
+
+    Resolution order:
+    1. Explicit *path* (YAML file).
+    2. ``.code-delivery.yml`` in the current working directory.
+    3. Environment variables.
+
+    YAML keys and env vars are merged (env wins on conflict).
+    """
+    yaml_data: dict[str, Any] = {}
+
+    candidates = [path] if path else [Path.cwd() / ".code-delivery.yml"]
+    for candidate in candidates:
+        if candidate and candidate.is_file():
+            try:
+                yaml_data = yaml.safe_load(candidate.read_text(encoding="utf-8")) or {}
+                logger.info("Loaded code-delivery config from %s", candidate)
+            except Exception as exc:
+                logger.warning("Failed to parse %s: %s", candidate, exc)
+            break
+
+    env_data = _config_from_env()
+
+    # Shallow merge: env overrides YAML at section level
+    merged: dict[str, Any] = {**yaml_data}
+    for key, value in env_data.items():
+        if isinstance(value, dict) and key in merged and isinstance(merged[key], dict):
+            merged[key] = {**merged[key], **value}
+        else:
+            merged[key] = value
+
+    return CodeDeliveryConfig(**merged)
+
+
+__all__ = [
+    "BackendConfig",
+    "CodeDeliveryConfig",
+    "GitHubConfig",
+    "HerdrConfig",
+    "load_config",
+]