agentx-kit 0.2.0__py3-none-any.whl

agentx/reliability.py

@@ -0,0 +1,112 @@
+"""Reliability: provider fallbacks, retries, and token/cost budgets.
+
+- ``build_resilient_chat`` wraps a primary model with retries and sequential
+  fallbacks to other providers/models (à la pydantic-ai's FallbackModel +
+  the 'circular fallback' pattern from production templates).
+- ``UsageLimits`` + ``UsageTracker`` enforce per-run request/token/cost budgets
+  to stop runaway agent loops (à la pydantic-ai ``UsageLimits``).
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from .providers import get_chat_model
+
+logger = logging.getLogger(__name__)
+
+
+def build_resilient_chat(
+    provider: str | None = None,
+    model: str | None = None,
+    fallbacks: list[tuple[str, str]] | None = None,
+    retries: int = 2,
+    **kwargs,
+):
+    """Return a chat model with retry + ordered provider/model fallbacks.
+
+    ``fallbacks`` is a list of ``(provider, model)`` tried in order if the
+    primary fails. Built on LangChain's ``.with_retry()`` / ``.with_fallbacks()``.
+    """
+    primary = get_chat_model(provider, model, **kwargs)
+    if retries and retries > 1:
+        primary = primary.with_retry(stop_after_attempt=retries, wait_exponential_jitter=True)
+    if fallbacks:
+        alts = []
+        for fb_provider, fb_model in fallbacks:
+            try:
+                alt = get_chat_model(fb_provider, fb_model, **kwargs)
+                alts.append(alt.with_retry(stop_after_attempt=retries, wait_exponential_jitter=True))
+            except Exception as exc:  # noqa: BLE001 - a missing extra shouldn't kill the chain
+                logger.warning("Skipping fallback %s/%s: %s", fb_provider, fb_model, exc)
+        if alts:
+            primary = primary.with_fallbacks(alts)
+    return primary
+
+
+class UsageLimitExceeded(RuntimeError):
+    """Raised when a configured request/token/cost budget is exceeded."""
+
+
+@dataclass
+class UsageLimits:
+    max_requests: int | None = None
+    max_total_tokens: int | None = None
+    max_cost_usd: float | None = None
+    # USD per 1K tokens (total). Override per your provider/model pricing.
+    price_per_1k_tokens: float = 0.0
+
+
+@dataclass
+class UsageTracker:
+    """Accumulates usage and enforces ``UsageLimits``.
+
+    Call :meth:`record` with token counts after each model call (or attach
+    :meth:`as_callback` to LangChain). Raises ``UsageLimitExceeded`` on breach.
+    """
+
+    limits: UsageLimits = field(default_factory=UsageLimits)
+    requests: int = 0
+    total_tokens: int = 0
+
+    @property
+    def cost_usd(self) -> float:
+        return round(self.total_tokens / 1000.0 * self.limits.price_per_1k_tokens, 6)
+
+    def record(self, tokens: int = 0) -> None:
+        self.requests += 1
+        self.total_tokens += max(0, int(tokens))
+        self._enforce()
+
+    def _enforce(self) -> None:
+        lim = self.limits
+        if lim.max_requests is not None and self.requests > lim.max_requests:
+            raise UsageLimitExceeded(f"max_requests exceeded ({self.requests} > {lim.max_requests})")
+        if lim.max_total_tokens is not None and self.total_tokens > lim.max_total_tokens:
+            raise UsageLimitExceeded(f"max_total_tokens exceeded ({self.total_tokens} > {lim.max_total_tokens})")
+        if lim.max_cost_usd is not None and self.cost_usd > lim.max_cost_usd:
+            raise UsageLimitExceeded(f"max_cost_usd exceeded (${self.cost_usd} > ${lim.max_cost_usd})")
+
+    def as_callback(self):
+        """Return a LangChain callback handler that records token usage."""
+        from langchain_core.callbacks import BaseCallbackHandler
+
+        tracker = self
+
+        class _UsageCallback(BaseCallbackHandler):
+            def on_llm_end(self, response, **kwargs):  # noqa: ANN001
+                tokens = 0
+                try:
+                    usage = (response.llm_output or {}).get("token_usage") or {}
+                    tokens = usage.get("total_tokens", 0)
+                    if not tokens:  # some providers attach usage to message metadata
+                        for gen in getattr(response, "generations", []) or []:
+                            for g in gen:
+                                meta = getattr(getattr(g, "message", None), "usage_metadata", None)
+                                if meta:
+                                    tokens += meta.get("total_tokens", 0)
+                except Exception:  # noqa: BLE001
+                    tokens = 0
+                tracker.record(tokens)
+
+        return _UsageCallback()

agentx/scaffold/__init__.py

@@ -0,0 +1,14 @@
+"""Scaffolder: interactive wizard + project generator + prompt management."""
+from .spec import AgentSpec, ProjectSpec
+from .generator import GenerationResult, generate_project
+from .wizard import run_wizard
+from . import prompts_store
+
+__all__ = [
+    "AgentSpec",
+    "ProjectSpec",
+    "GenerationResult",
+    "generate_project",
+    "run_wizard",
+    "prompts_store",
+]

agentx/scaffold/generator.py

@@ -0,0 +1,190 @@
+"""Project generator — renders templates into a new project and sets up uv.
+
+``generate_project(spec, target_dir)`` is pure/testable: it writes files and,
+unless disabled, runs ``uv venv`` (creating ``.venv``) and optionally ``uv sync``.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from ..providers import get_spec
+from . import prompts_store
+from .spec import ProjectSpec
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+# (template, output-relative-path, include?) — output paths use {pkg} placeholder.
+_FILE_PLAN: list[tuple[str, str]] = [
+    ("pyproject.toml.j2", "pyproject.toml"),
+    ("README.md.j2", "README.md"),
+    ("env.example.j2", ".env.example"),
+    ("gitignore.j2", ".gitignore"),
+    ("pkg/__init__.py.j2", "src/{pkg}/__init__.py"),
+    ("pkg/config.py.j2", "src/{pkg}/config.py"),
+    ("pkg/prompts.py.j2", "src/{pkg}/prompts.py"),
+    ("pkg/agents.py.j2", "src/{pkg}/agents.py"),
+    ("pkg/main.py.j2", "src/{pkg}/main.py"),
+]
+
+
+@dataclass
+class GenerationResult:
+    target_dir: Path
+    files: list[Path]
+    venv_created: bool
+    synced: bool
+    messages: list[str]
+
+
+def _extras(spec: ProjectSpec) -> list[str]:
+    """Compute the agentx extras the generated project needs."""
+    extras = {get_spec(spec.provider).extra}
+    extras.add("langgraph" if spec.framework == "langgraph" else "crewai")
+    if spec.use_rag:
+        extras.add("rag")
+    if spec.use_mcp:
+        extras.add("mcp")
+    if spec.observability:
+        extras.add("observability")
+    if spec.serve:
+        extras.add("server")
+    # Deterministic order for reproducible pyproject output.
+    order = ["langgraph", "crewai", "openai", "azure", "openrouter", "anthropic",
+             "google", "vertex", "bedrock", "groq", "ollama", "rag", "mcp",
+             "observability", "server"]
+    return [e for e in order if e in extras]
+
+
+def _context(spec: ProjectSpec) -> dict:
+    provider_spec = get_spec(spec.provider)
+    return {
+        "spec": spec,
+        "pkg": spec.package,
+        "model": spec.model or provider_spec.default_model,
+        "provider_label": provider_spec.label,
+        "provider_env": list(provider_spec.env_vars),
+        "extras": _extras(spec),
+        "extras_str": ",".join(_extras(spec)),
+    }
+
+
+def _env() -> Environment:
+    return Environment(
+        loader=FileSystemLoader(str(TEMPLATES_DIR)),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+        undefined=StrictUndefined,
+    )
+
+
+def _conditional_files(spec: ProjectSpec) -> list[tuple[str, str]]:
+    plan: list[tuple[str, str]] = []
+    if spec.use_rag:
+        plan.append(("pkg/rag.py.j2", "src/{pkg}/rag.py"))
+    if spec.needs_memory:
+        plan.append(("pkg/memory.py.j2", "src/{pkg}/memory.py"))
+    if spec.use_mcp:
+        plan.append(("pkg/tools.py.j2", "src/{pkg}/tools.py"))
+        plan.append(("mcp_servers.json.j2", "mcp_servers.json"))
+    if spec.use_skills:
+        plan.append(("skills_seed.json.j2", "data/skills/star-method.json"))
+    if spec.observability:
+        plan.append(("pkg/observability.py.j2", "src/{pkg}/observability.py"))
+    if spec.guardrails:
+        plan.append(("pkg/guardrails.py.j2", "src/{pkg}/guardrails.py"))
+    if spec.serve:
+        plan.append(("pkg/server.py.j2", "src/{pkg}/server.py"))
+    if spec.docker:
+        plan.append(("Dockerfile.j2", "Dockerfile"))
+        plan.append(("docker-compose.yml.j2", "docker-compose.yml"))
+        plan.append(("dockerignore.j2", ".dockerignore"))
+    if spec.ci:
+        plan.append(("ci.yml.j2", ".github/workflows/ci.yml"))
+    if spec.evals:
+        plan.append(("evals/run_evals.py.j2", "evals/run_evals.py"))
+        plan.append(("evals/dataset.json.j2", "evals/dataset.json"))
+    return plan
+
+
+def _write_manifest(target: Path, spec: ProjectSpec) -> Path:
+    """Write agentx.json — a declarative summary of the generated project."""
+    import json
+
+    manifest = {
+        "name": spec.slug,
+        "framework": spec.framework,
+        "provider": spec.provider,
+        "model": spec.model or get_spec(spec.provider).default_model,
+        "python_version": ">=3.10,<3.14",
+        "agents": [a.name for a in spec.agents],
+        "features": {
+            "rag": spec.use_rag,
+            "memory": spec.memory,
+            "mcp": spec.use_mcp,
+            "skills": spec.use_skills,
+            "observability": spec.observability,
+            "guardrails": spec.guardrails,
+            "serve": spec.serve,
+            "docker": spec.docker,
+            "ci": spec.ci,
+            "evals": spec.evals,
+        },
+        "extras": _extras(spec),
+        "telemetry_opt_out": False,
+    }
+    path = target / "agentx.json"
+    path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def generate_project(spec: ProjectSpec, target_dir: str | Path, overwrite: bool = False) -> GenerationResult:
+    """Render the project for ``spec`` into ``target_dir``."""
+    target = Path(target_dir).expanduser().resolve()
+    if target.exists() and any(target.iterdir()) and not overwrite:
+        raise FileExistsError(f"Target directory '{target}' exists and is not empty. Use overwrite=True.")
+    target.mkdir(parents=True, exist_ok=True)
+
+    env = _env()
+    ctx = _context(spec)
+    written: list[Path] = []
+    messages: list[str] = []
+
+    for template_name, out_rel in _FILE_PLAN + _conditional_files(spec):
+        out_path = target / out_rel.format(pkg=spec.package)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        rendered = env.get_template(template_name).render(**ctx)
+        out_path.write_text(rendered, encoding="utf-8")
+        written.append(out_path)
+
+    # The prompt source of truth — edited by hand or via `agentx prompt`.
+    written.append(prompts_store.write_prompts(target, spec))
+    # A single declarative manifest of the project (à la langgraph.json).
+    written.append(_write_manifest(target, spec))
+
+    venv_created = synced = False
+    uv = shutil.which("uv")
+    if spec.create_venv:
+        if not uv:
+            messages.append("`uv` not found on PATH — skipped .venv creation. Install uv: https://docs.astral.sh/uv/")
+        else:
+            try:
+                subprocess.run([uv, "venv"], cwd=target, check=True, capture_output=True, timeout=120)
+                venv_created = True
+                messages.append("Created .venv via `uv venv`.")
+            except Exception as exc:  # noqa: BLE001
+                messages.append(f"`uv venv` failed: {exc!r}")
+            if venv_created and spec.run_sync:
+                try:
+                    subprocess.run([uv, "sync"], cwd=target, check=True, timeout=900)
+                    synced = True
+                    messages.append("Installed dependencies via `uv sync`.")
+                except Exception as exc:  # noqa: BLE001
+                    messages.append(f"`uv sync` failed (run it manually): {exc!r}")
+
+    return GenerationResult(target, written, venv_created, synced, messages)

agentx/scaffold/prompts_store.py

@@ -0,0 +1,99 @@
+"""Read/write helpers for a generated project's ``prompts.json``.
+
+The generated project is *prompt-file driven*: ``prompts.json`` is the source of
+truth for which agents exist and what their system prompts are. Editing it (by
+hand or via ``agentx prompt``) changes the running project — no code edits needed.
+
+Schema::
+
+    {
+      "with_rag": false,
+      "agents": {
+        "<name>": {"role": "...", "goal": "...", "system_prompt": "..."}
+      }
+    }
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .spec import ProjectSpec, to_snake
+
+FILENAME = "prompts.json"
+
+
+def build_prompts_data(spec: ProjectSpec) -> dict:
+    """Build the prompts.json payload from a ProjectSpec."""
+    return {
+        "with_rag": spec.use_rag,
+        "agents": {
+            a.name: {"role": a.role, "goal": a.goal, "system_prompt": a.system_prompt}
+            for a in spec.agents
+        },
+    }
+
+
+def write_prompts(target_dir: str | Path, spec: ProjectSpec) -> Path:
+    path = Path(target_dir) / FILENAME
+    path.write_text(json.dumps(build_prompts_data(spec), indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def find_prompts_file(start: str | Path | None = None) -> Path | None:
+    """Walk up from ``start`` (or cwd) to find a project's prompts.json."""
+    base = Path(start or Path.cwd()).resolve()
+    for d in [base, *base.parents]:
+        candidate = d / FILENAME
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load(path: str | Path) -> dict:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    data.setdefault("agents", {})
+    data.setdefault("with_rag", False)
+    return data
+
+
+def save(path: str | Path, data: dict) -> None:
+    Path(path).write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def set_prompt(path: str | Path, name: str, text: str) -> dict:
+    """Set/replace an existing agent's system prompt."""
+    data = load(path)
+    key = to_snake(name)
+    if key not in data["agents"]:
+        raise KeyError(f"No agent named '{key}'. Use `add` to create it.")
+    data["agents"][key]["system_prompt"] = text
+    save(path, data)
+    return data
+
+
+def add_agent(path: str | Path, name: str, role: str = "", goal: str = "", text: str = "") -> dict:
+    """Add a new agent. The project picks it up automatically on next run."""
+    data = load(path)
+    key = to_snake(name)
+    if key in data["agents"]:
+        raise KeyError(f"Agent '{key}' already exists. Use `set` to change its prompt.")
+    data["agents"][key] = {
+        "role": role or f"{name} agent",
+        "goal": goal or "Help the user accomplish their task accurately.",
+        "system_prompt": text,
+    }
+    save(path, data)
+    return data
+
+
+def remove_agent(path: str | Path, name: str) -> dict:
+    data = load(path)
+    key = to_snake(name)
+    if key not in data["agents"]:
+        raise KeyError(f"No agent named '{key}'.")
+    if len(data["agents"]) == 1:
+        raise ValueError("Cannot remove the last remaining agent.")
+    del data["agents"][key]
+    save(path, data)
+    return data

agentx/scaffold/spec.py

@@ -0,0 +1,85 @@
+"""``ProjectSpec`` — the single source of truth for a generation run.
+
+Both the interactive wizard and the programmatic API produce a ``ProjectSpec``;
+the generator consumes it. Keeping this validated and standalone makes the whole
+scaffolder testable without a TTY.
+"""
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+Framework = Literal["langgraph", "crewai"]
+MemoryMode = Literal["none", "short", "long", "both"]
+PromptStyle = Literal["default", "custom"]
+
+
+def to_snake(name: str) -> str:
+    s = re.sub(r"[^0-9a-zA-Z]+", "_", name.strip().lower()).strip("_")
+    return s or "app"
+
+
+class AgentSpec(BaseModel):
+    name: str = "assistant"
+    role: str = "Helpful Assistant"
+    goal: str = "Help the user accomplish their task accurately."
+    # Optional explicit system prompt. Blank → derived from role/goal at runtime.
+    system_prompt: str = ""
+
+    @field_validator("name")
+    @classmethod
+    def _slug(cls, v: str) -> str:
+        return to_snake(v)
+
+
+class ProjectSpec(BaseModel):
+    name: str = Field(..., description="Project name (directory + package base).")
+    framework: Framework = "langgraph"
+    provider: str = "openai"
+    model: str = ""                       # blank → provider default
+    agents: list[AgentSpec] = Field(default_factory=lambda: [AgentSpec()])
+    use_rag: bool = False
+    memory: MemoryMode = "none"
+    use_mcp: bool = False
+    use_skills: bool = False
+    prompt_style: PromptStyle = "default"
+    # ----- enterprise features -----
+    observability: bool = False   # OpenTelemetry / Langfuse tracing wiring
+    guardrails: bool = False      # input/output guardrails module
+    serve: bool = False           # FastAPI server (REST + SSE streaming)
+    docker: bool = False          # Dockerfile + docker-compose.yml
+    ci: bool = False              # GitHub Actions (lint + test [+ eval])
+    evals: bool = False           # LLM-as-judge eval harness (+ CI gate)
+    create_venv: bool = True
+    run_sync: bool = False
+    # When set, generated pyproject depends on agentx from this local path
+    # (editable) instead of PyPI — used for local dev/testing.
+    agentx_local_path: str | None = None
+
+    def enable_enterprise(self) -> "ProjectSpec":
+        """Turn on the full enterprise feature set in one call."""
+        self.observability = self.guardrails = self.serve = True
+        self.docker = self.ci = self.evals = True
+        return self
+
+    @property
+    def package(self) -> str:
+        return to_snake(self.name)
+
+    @property
+    def slug(self) -> str:
+        return re.sub(r"[^0-9a-zA-Z]+", "-", self.name.strip().lower()).strip("-") or "app"
+
+    @property
+    def needs_memory(self) -> bool:
+        return self.memory != "none"
+
+    @property
+    def use_short_memory(self) -> bool:
+        return self.memory in ("short", "both")
+
+    @property
+    def use_long_memory(self) -> bool:
+        return self.memory in ("long", "both")

agentx/scaffold/templates/Dockerfile.j2

@@ -0,0 +1,17 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+WORKDIR /app
+
+# uv for fast, reproducible installs
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+COPY . .
+RUN uv pip install --system .
+
+{% if spec.serve %}
+EXPOSE 8000
+CMD ["uvicorn", "{{ pkg }}.server:app", "--host", "0.0.0.0", "--port", "8000"]
+{% else %}
+CMD ["python", "-m", "{{ pkg }}.main"]
+{% endif %}

agentx/scaffold/templates/README.md.j2

@@ -0,0 +1,46 @@
+# {{ spec.slug }}
+
+Agentic app generated by **AgentX**.
+
+- **Framework:** {{ spec.framework }}
+- **Provider:** {{ provider_label }} (`{{ model }}`)
+- **Agents:** {% for a in spec.agents %}`{{ a.name }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+- **RAG:** {{ "yes" if spec.use_rag else "no" }}
+- **Memory:** {{ spec.memory }}
+- **MCP tools:** {{ "yes" if spec.use_mcp else "no" }}
+- **Skills:** {{ "yes" if spec.use_skills else "no" }}
+
+## Setup
+```bash
+uv sync                 # install dependencies into .venv
+cp .env.example .env    # then fill in your credentials
+```
+
+## Run
+```bash
+uv run {{ spec.slug }}
+# or:
+uv run python -m {{ pkg }}.main
+```
+
+## Layout
+```
+src/{{ pkg }}/
+├── config.py     # provider/model selection
+├── prompts.py    # per-agent system prompts
+├── agents.py     # agent (and crew) definitions
+{% if spec.use_rag %}├── rag.py        # knowledge base / retriever tool
+{% endif %}
+{% if spec.needs_memory %}├── memory.py     # conversation / long-term memory
+{% endif %}
+{% if spec.use_mcp %}├── tools.py      # MCP tool loading
+{% endif %}
+└── main.py       # entry point
+```
+{% if spec.use_rag %}
+Add `.txt`/`.md` files under `knowledge/` to populate the RAG index.
+{% endif %}
+{% if spec.use_mcp %}
+Edit `mcp_servers.json` to configure your MCP servers.
+{% endif %}

agentx/scaffold/templates/ci.yml.j2

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv pip install --system -e . pytest ruff
+      - name: Lint
+        run: ruff check . || true
+      - name: Compile
+        run: python -m compileall src
+      - name: Tests
+        run: pytest -q || echo "no tests yet"
+{% if spec.evals %}
+
+  evals:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv pip install --system -e .
+      - name: Run eval gate
+        env:
+          # Add your provider key as a repo secret to enable the gate.
+          OPENAI_API_KEY: {% raw %}${{ secrets.OPENAI_API_KEY }}{% endraw %}
+
+        run: python evals/run_evals.py
+{% endif %}

agentx/scaffold/templates/docker-compose.yml.j2

@@ -0,0 +1,9 @@
+services:
+  {{ spec.slug }}:
+    build: .
+    env_file: .env
+{% if spec.serve %}
+    ports:
+      - "8000:8000"
+{% endif %}
+    restart: unless-stopped

agentx/scaffold/templates/dockerignore.j2

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+.git/
+.github/
+.env
+data/
+.chroma/
+tests/
+evals/
+.pytest_cache/

agentx/scaffold/templates/env.example.j2

@@ -0,0 +1,12 @@
+# --- Provider selection (read by agentx) ---
+AGENTX_PROVIDER={{ spec.provider }}
+AGENTX_MODEL={{ model }}
+AGENTX_TEMPERATURE=0.3
+
+# --- Credentials for {{ provider_label }} ---
+{% for v in provider_env %}
+{{ v }}=
+{% endfor %}
+{% if not provider_env %}
+# {{ provider_label }} is local — no API key required.
+{% endif %}

agentx/scaffold/templates/evals/dataset.json.j2

@@ -0,0 +1,10 @@
+[
+  {
+    "input": "Say hello and briefly state what you can help with.",
+    "criteria": "Greets the user and clearly explains the agent's purpose/capabilities."
+  },
+  {
+    "input": "What are your main capabilities?",
+    "criteria": "Lists relevant, concrete capabilities without hallucinating unavailable features."
+  }
+]