agentx-kit 0.2.0__py3-none-any.whl

agentx/__init__.py

@@ -0,0 +1,55 @@
+"""AgentX — provider-agnostic agentic framework + project scaffolder.
+
+Quick start (library):
+
+    from agentx import get_chat_model
+    llm = get_chat_model("openai", "gpt-4o-mini")
+    print(llm.invoke("Hello").content)
+
+Quick start (scaffolder):
+
+    $ agentx new            # interactive wizard → generates a uv project
+
+Public API is intentionally small and stable; capability modules (rag, memory,
+tools, skills, frameworks) are imported lazily so installing one provider extra
+is enough to get started.
+"""
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .providers import (  # noqa: E402
+    ProviderSpec,
+    get_chat_model,
+    get_crewai_llm,
+    list_providers,
+)
+from .guardrails import GuardrailError, apply_guards  # noqa: E402
+from .observability import get_callbacks, setup_tracing, telemetry_enabled  # noqa: E402
+from .reliability import (  # noqa: E402
+    UsageLimitExceeded,
+    UsageLimits,
+    UsageTracker,
+    build_resilient_chat,
+)
+from .structured import structured_model  # noqa: E402
+
+__all__ = [
+    "__version__",
+    # providers
+    "ProviderSpec",
+    "get_chat_model",
+    "get_crewai_llm",
+    "list_providers",
+    # enterprise runtime
+    "setup_tracing",
+    "get_callbacks",
+    "telemetry_enabled",
+    "build_resilient_chat",
+    "UsageLimits",
+    "UsageTracker",
+    "UsageLimitExceeded",
+    "apply_guards",
+    "GuardrailError",
+    "structured_model",
+]

agentx/cli.py

@@ -0,0 +1,230 @@
+"""AgentX command-line interface.
+
+    agentx new          # interactive wizard → scaffold a project
+    agentx providers    # list supported LLM providers + required env vars
+    agentx version
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from . import __version__
+from .providers import all_specs, get_spec
+from .scaffold import AgentSpec, ProjectSpec, generate_project, run_wizard
+from .scaffold import prompts_store
+
+app = typer.Typer(
+    add_completion=False,
+    help="AgentX — provider-agnostic agentic framework + project scaffolder.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def version() -> None:
+    """Print the installed version."""
+    console.print(f"agentx {__version__}")
+
+
+@app.command()
+def providers() -> None:
+    """List supported LLM providers and the env vars each needs."""
+    table = Table(title="Supported LLM providers", show_lines=False)
+    table.add_column("id", style="cyan", no_wrap=True)
+    table.add_column("provider")
+    table.add_column("extra", style="green")
+    table.add_column("default model")
+    table.add_column("env vars", style="yellow")
+    for s in all_specs():
+        table.add_row(s.id, s.label, s.extra, s.default_model, ", ".join(s.env_vars) or "— (local)")
+    console.print(table)
+
+
+def _result_panel(result, spec: ProjectSpec) -> None:
+    lines = [f"[bold green]✓[/] Project '{spec.slug}' created at:", f"  {result.target_dir}", ""]
+    lines += [f"  • {m}" for m in result.messages]
+    lines += [
+        "",
+        "[bold]Next steps:[/]",
+        f"  cd {result.target_dir.name}",
+        "  cp .env.example .env   # add your credentials",
+        "  uv sync" if not result.synced else "  # deps already installed",
+        f"  uv run {spec.slug}",
+    ]
+    console.print(Panel("\n".join(lines), title="AgentX", border_style="cyan"))
+
+
+@app.command()
+def new(
+    name: str = typer.Option(None, "--name", "-n", help="Project name."),
+    out: Path = typer.Option(None, "--out", "-o", help="Target directory (default ./<name>)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Non-interactive: use defaults + options below."),
+    framework: str = typer.Option("langgraph", help="langgraph | crewai (with --yes)."),
+    provider: str = typer.Option("openai", help="Provider id (with --yes)."),
+    model: str = typer.Option("", help="Model id (with --yes; blank = provider default)."),
+    agents: int = typer.Option(1, help="Number of agents (with --yes)."),
+    prompt: str = typer.Option("", "--prompt", "-p", help="System prompt for the first agent (with --yes)."),
+    role: str = typer.Option("Helpful Assistant", help="Role for the first agent (with --yes)."),
+    goal: str = typer.Option("Help the user accomplish their task accurately.", help="Goal for the first agent (with --yes)."),
+    rag: bool = typer.Option(False, help="Include RAG (with --yes)."),
+    memory: str = typer.Option("none", help="none|short|long|both (with --yes)."),
+    mcp: bool = typer.Option(False, help="Include MCP tools (with --yes)."),
+    skills: bool = typer.Option(False, help="Include skills registry (with --yes)."),
+    enterprise: bool = typer.Option(False, "--enterprise", help="Enable the full enterprise pack (tracing, guardrails, FastAPI, Docker, CI, evals)."),
+    observability: bool = typer.Option(False, help="OpenTelemetry/Langfuse observability (with --yes)."),
+    guardrails: bool = typer.Option(False, help="Input/output guardrails (with --yes)."),
+    serve: bool = typer.Option(False, help="FastAPI server (REST + SSE) (with --yes)."),
+    docker: bool = typer.Option(False, help="Dockerfile + docker-compose (with --yes)."),
+    ci: bool = typer.Option(False, help="GitHub Actions CI (with --yes)."),
+    evals: bool = typer.Option(False, help="LLM-as-judge eval harness (with --yes)."),
+    no_venv: bool = typer.Option(False, "--no-venv", help="Do not create a .venv."),
+    sync: bool = typer.Option(False, "--sync", help="Run `uv sync` after generating."),
+    overwrite: bool = typer.Option(False, help="Overwrite a non-empty target directory."),
+) -> None:
+    """Scaffold a new agentic project (interactive by default)."""
+    if yes:
+        try:
+            get_spec(provider)
+        except KeyError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+        agent_specs = []
+        for i in range(max(1, agents)):
+            a_name = f"agent_{i+1}" if agents > 1 else "assistant"
+            # The --prompt/--role/--goal flags configure the first agent.
+            if i == 0:
+                agent_specs.append(AgentSpec(name=a_name, role=role, goal=goal, system_prompt=prompt))
+            else:
+                agent_specs.append(AgentSpec(name=a_name))
+        spec = ProjectSpec(
+            name=name or "my-agent", framework=framework, provider=provider, model=model,
+            agents=agent_specs, use_rag=rag, memory=memory, use_mcp=mcp, use_skills=skills,
+            prompt_style="custom" if prompt else "default",
+            observability=observability, guardrails=guardrails, serve=serve,
+            docker=docker, ci=ci, evals=evals,
+            create_venv=not no_venv, run_sync=sync,
+        )
+        if enterprise:
+            spec.enable_enterprise()
+    else:
+        spec = run_wizard(name)
+        if spec is None:
+            console.print("[yellow]Cancelled.[/]")
+            raise typer.Exit(1)
+        if enterprise:
+            spec.enable_enterprise()
+        if no_venv:
+            spec.create_venv = False
+        if sync:
+            spec.run_sync = True
+
+    target = out or Path.cwd() / spec.slug
+    try:
+        result = generate_project(spec, target, overwrite=overwrite)
+    except FileExistsError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    _result_panel(result, spec)
+
+
+# --------------------------------------------------------------------------- #
+# `agentx prompt …` — manage prompts in an EXISTING generated project
+# --------------------------------------------------------------------------- #
+prompt_app = typer.Typer(help="Manage agent prompts in a generated project (edits prompts.json).", no_args_is_help=True)
+app.add_typer(prompt_app, name="prompt")
+
+
+def _resolve_prompts_file(project: Path | None) -> Path:
+    path = prompts_store.find_prompts_file(project)
+    if path is None:
+        console.print(
+            "[red]No prompts.json found.[/] Run this inside a AgentX project "
+            "(or pass --project /path/to/project)."
+        )
+        raise typer.Exit(1)
+    return path
+
+
+def _read_text_arg(text: str | None, from_file: Path | None) -> str:
+    if from_file:
+        return Path(from_file).read_text(encoding="utf-8").strip()
+    return (text or "").strip()
+
+
+@prompt_app.command("list")
+def prompt_list(project: Path = typer.Option(None, "--project", help="Project dir (default: search from cwd).")) -> None:
+    """List agents and their (resolved) prompts."""
+    path = _resolve_prompts_file(project)
+    data = prompts_store.load(path)
+    table = Table(title=f"Agents in {path.parent.name}/prompts.json")
+    table.add_column("agent", style="cyan")
+    table.add_column("role")
+    table.add_column("prompt", overflow="fold")
+    for name, meta in data.get("agents", {}).items():
+        sp = meta.get("system_prompt") or f"(auto from role/goal: {meta.get('goal','')})"
+        table.add_row(name, meta.get("role", ""), sp)
+    console.print(table)
+
+
+@prompt_app.command("set")
+def prompt_set(
+    agent: str = typer.Argument(..., help="Agent name to update."),
+    text: str = typer.Option("", "--text", "-t", help="New system prompt text."),
+    from_file: Path = typer.Option(None, "--file", "-f", help="Read prompt text from a file."),
+    project: Path = typer.Option(None, "--project"),
+) -> None:
+    """Set/replace an existing agent's system prompt."""
+    path = _resolve_prompts_file(project)
+    body = _read_text_arg(text, from_file)
+    if not body:
+        body = typer.edit("\n# Enter the system prompt above this line.\n") or ""
+        body = body.split("\n# Enter the system prompt")[0].strip()
+    try:
+        prompts_store.set_prompt(path, agent, body)
+    except KeyError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]✓[/] Updated prompt for '{agent}'.")
+
+
+@prompt_app.command("add")
+def prompt_add(
+    agent: str = typer.Argument(..., help="New agent name."),
+    role: str = typer.Option("", "--role"),
+    goal: str = typer.Option("", "--goal"),
+    text: str = typer.Option("", "--text", "-t", help="System prompt (blank = auto from role/goal)."),
+    from_file: Path = typer.Option(None, "--file", "-f"),
+    project: Path = typer.Option(None, "--project"),
+) -> None:
+    """Add a new agent; the project picks it up automatically on next run."""
+    path = _resolve_prompts_file(project)
+    try:
+        prompts_store.add_agent(path, agent, role=role, goal=goal, text=_read_text_arg(text, from_file))
+    except KeyError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]✓[/] Added agent '{agent}'. It will run on next start — no code changes needed.")
+
+
+@prompt_app.command("remove")
+def prompt_remove(
+    agent: str = typer.Argument(..., help="Agent name to remove."),
+    project: Path = typer.Option(None, "--project"),
+) -> None:
+    """Remove an agent from the project."""
+    path = _resolve_prompts_file(project)
+    try:
+        prompts_store.remove_agent(path, agent)
+    except (KeyError, ValueError) as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]✓[/] Removed agent '{agent}'.")
+
+
+if __name__ == "__main__":
+    app()

agentx/config.py

@@ -0,0 +1,34 @@
+"""Runtime configuration for the agentx library (pydantic-settings).
+
+Reads from environment / a local ``.env``. Only generic, cross-provider knobs
+live here; provider credentials are read by each provider's SDK from their own
+standard env vars (see ``agentx.providers.registry``).
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    # Default provider/model used when none is passed explicitly.
+    default_provider: str = Field(default="openai", alias="AGENTX_PROVIDER")
+    default_model: str = Field(default="", alias="AGENTX_MODEL")
+    temperature: float = Field(default=0.3, alias="AGENTX_TEMPERATURE")
+    max_tokens: int | None = Field(default=None, alias="AGENTX_MAX_TOKENS")
+    request_timeout: int = Field(default=120, alias="AGENTX_REQUEST_TIMEOUT")
+
+    # Local backends.
+    ollama_base_url: str = Field(default="http://localhost:11434", alias="OLLAMA_BASE_URL")
+    openrouter_base_url: str = Field(
+        default="https://openrouter.ai/api/v1", alias="OPENROUTER_BASE_URL"
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

agentx/frameworks/__init__.py

@@ -0,0 +1,5 @@
+"""Framework adapters — build agents on LangGraph or CrewAI from common inputs."""
+from .langchain_agent import build_react_agent, run_agent
+from .crewai_agent import build_crewai_agent, build_crew
+
+__all__ = ["build_react_agent", "run_agent", "build_crewai_agent", "build_crew"]

agentx/frameworks/crewai_agent.py

@@ -0,0 +1,52 @@
+"""CrewAI adapter — build Agents and a Crew from common inputs.
+
+Uses our provider factory's ``get_crewai_llm`` so the same provider ids work
+across frameworks. Requires ``agentx-kit[crewai]``.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..providers import get_crewai_llm
+
+
+def _require_crewai():
+    try:
+        import crewai  # type: ignore
+
+        return crewai
+    except ImportError as exc:
+        raise ImportError(
+            "CrewAI is required. Install with: uv pip install 'agentx-kit[crewai]'"
+        ) from exc
+
+
+def build_crewai_agent(
+    role: str,
+    goal: str,
+    backstory: str = "",
+    provider: str | None = None,
+    model: str | None = None,
+    tools: list[Any] | None = None,
+    **kwargs: Any,
+):
+    """Return a configured CrewAI ``Agent``."""
+    crewai = _require_crewai()
+    llm = get_crewai_llm(provider, model)
+    return crewai.Agent(
+        role=role,
+        goal=goal,
+        backstory=backstory or f"An expert acting as {role}.",
+        tools=tools or [],
+        llm=llm,
+        verbose=kwargs.pop("verbose", True),
+        allow_delegation=kwargs.pop("allow_delegation", False),
+        **kwargs,
+    )
+
+
+def build_crew(agents: list[Any], tasks: list[Any], **kwargs: Any):
+    """Return a CrewAI ``Crew`` from agents + tasks (sequential by default)."""
+    crewai = _require_crewai()
+    process = kwargs.pop("process", None) or crewai.Process.sequential
+    return crewai.Crew(agents=agents, tasks=tasks, process=process, verbose=kwargs.pop("verbose", True), **kwargs)

agentx/frameworks/langchain_agent.py

@@ -0,0 +1,43 @@
+"""LangGraph agent adapter.
+
+``build_react_agent`` wires a provider-agnostic chat model (from our factory) +
+tools + an optional system prompt into a LangGraph ReAct agent. Requires
+``agentx-kit[langgraph]`` plus the chosen provider extra.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..providers import get_chat_model
+
+
+def build_react_agent(
+    provider: str | None = None,
+    model: str | None = None,
+    tools: list[Any] | None = None,
+    system_prompt: str | None = None,
+    **model_kwargs: Any,
+):
+    """Return a compiled LangGraph ReAct agent (a runnable)."""
+    try:
+        from langgraph.prebuilt import create_react_agent
+    except ImportError as exc:
+        raise ImportError(
+            "LangGraph is required. Install with: uv pip install 'agentx-kit[langgraph]'"
+        ) from exc
+
+    llm = get_chat_model(provider, model, **model_kwargs)
+    tools = tools or []
+    if system_prompt:
+        return create_react_agent(llm, tools, prompt=system_prompt)
+    return create_react_agent(llm, tools)
+
+
+def run_agent(agent, user_input: str) -> str:
+    """Invoke a LangGraph agent with a single user message; return final text."""
+    result = agent.invoke({"messages": [{"role": "user", "content": user_input}]})
+    messages = result.get("messages", []) if isinstance(result, dict) else []
+    if messages:
+        last = messages[-1]
+        return getattr(last, "content", None) or (last.get("content", "") if isinstance(last, dict) else "")
+    return str(result)

agentx/guardrails.py

@@ -0,0 +1,89 @@
+"""Guardrails: input/output validation, PII redaction, and content checks.
+
+Lightweight, dependency-free defaults that cover the common enterprise asks
+(PII redaction, banned content, length caps). Compose your own by passing
+callables to :func:`apply_guards`. For heavier needs (jailbreak/moderation),
+wire in Guardrails-AI or NeMo Guardrails in your project.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_PII_PATTERNS = {
+    "email": re.compile(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"),
+    "phone": re.compile(r"\b(?:\+?\d{1,3}[\s.-]?)?(?:\(?\d{3}\)?[\s.-]?)\d{3}[\s.-]?\d{4}\b"),
+    "ssn": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+    "credit_card": re.compile(r"\b(?:\d[ -]?){13,16}\b"),
+}
+
+
+class GuardrailError(ValueError):
+    """Raised by a guard when input/output is rejected outright."""
+
+
+@dataclass
+class GuardResult:
+    text: str
+    violations: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.violations
+
+
+def redact_pii(text: str, kinds: tuple[str, ...] | None = None) -> GuardResult:
+    """Replace detected PII with ``[REDACTED:<kind>]``."""
+    out = text
+    found: list[str] = []
+    for kind, pattern in _PII_PATTERNS.items():
+        if kinds and kind not in kinds:
+            continue
+        if pattern.search(out):
+            found.append(f"pii:{kind}")
+            out = pattern.sub(f"[REDACTED:{kind}]", out)
+    return GuardResult(out, found)
+
+
+def block_banned(text: str, banned: list[str]) -> GuardResult:
+    lowered = text.lower()
+    hits = [w for w in banned if w.lower() in lowered]
+    return GuardResult(text, [f"banned:{w}" for w in hits])
+
+
+def enforce_max_length(text: str, max_chars: int) -> GuardResult:
+    if len(text) > max_chars:
+        return GuardResult(text[:max_chars], [f"truncated:{len(text)}>{max_chars}"])
+    return GuardResult(text)
+
+
+def apply_guards(text: str, guards: list, raise_on_violation: bool = False) -> GuardResult:
+    """Run guards in order, threading the (possibly transformed) text through.
+
+    Each guard is a callable ``str -> GuardResult``. Violations accumulate.
+    """
+    violations: list[str] = []
+    current = text
+    for guard in guards:
+        result = guard(current)
+        current = result.text
+        violations.extend(result.violations)
+    if violations and raise_on_violation:
+        raise GuardrailError("; ".join(violations))
+    return GuardResult(current, violations)
+
+
+def default_input_guards(banned: list[str] | None = None, max_chars: int = 8000) -> list:
+    return [
+        lambda t: enforce_max_length(t, max_chars),
+        lambda t: block_banned(t, banned or []),
+    ]
+
+
+def default_output_guards(redact: bool = True, max_chars: int = 16000) -> list:
+    # Redact first, then cap length last so max_chars is the final guarantee.
+    guards = []
+    if redact:
+        guards.append(lambda t: redact_pii(t))
+    guards.append(lambda t: enforce_max_length(t, max_chars))
+    return guards

agentx/memory/__init__.py

@@ -0,0 +1,4 @@
+"""Agent memory: short-term (windowed) + long-term (persistent JSONL)."""
+from .store import ConversationMemory, LongTermMemory
+
+__all__ = ["ConversationMemory", "LongTermMemory"]

agentx/memory/store.py

@@ -0,0 +1,78 @@
+"""Two-tier agent memory — dependency-free, works with any framework.
+
+* ``ConversationMemory`` — short-term, in-process windowed buffer of turns.
+* ``LongTermMemory``    — append-only JSONL persisted per session, survives restarts.
+"""
+from __future__ import annotations
+
+import json
+import threading
+from collections import deque
+from datetime import datetime, timezone
+from pathlib import Path
+
+_lock = threading.Lock()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class ConversationMemory:
+    """A rolling window of the most recent (role, content) turns."""
+
+    def __init__(self, max_turns: int = 12):
+        self.max_turns = max_turns
+        self._turns: deque[tuple[str, str]] = deque(maxlen=max_turns)
+
+    def add(self, role: str, content: str) -> None:
+        self._turns.append((role, content))
+
+    def add_user(self, content: str) -> None:
+        self.add("user", content)
+
+    def add_ai(self, content: str) -> None:
+        self.add("assistant", content)
+
+    def as_messages(self) -> list[dict]:
+        """Return turns as chat-style message dicts."""
+        return [{"role": r, "content": c} for r, c in self._turns]
+
+    def transcript(self) -> str:
+        return "\n".join(f"{r}: {c}" for r, c in self._turns)
+
+    def clear(self) -> None:
+        self._turns.clear()
+
+
+class LongTermMemory:
+    """Append-only JSONL memory keyed by session id."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def add(self, role: str, content: str, **meta) -> dict:
+        event = {"ts": _now(), "role": role, "content": content, **meta}
+        with _lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(event) + "\n")
+        return event
+
+    def history(self, limit: int | None = None) -> list[dict]:
+        if not self.path.exists():
+            return []
+        rows = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return rows[-limit:] if limit else rows
+
+    def clear(self) -> None:
+        if self.path.exists():
+            self.path.unlink()