agentx-kit 0.2.0__py3-none-any.whl

agentx/scaffold/templates/evals/run_evals.py.j2

@@ -0,0 +1,70 @@
+"""LLM-as-judge eval harness for {{ spec.slug }}.
+
+Runs each case in evals/dataset.json through the agent, scores the output with a
+judge LLM (0-1) against the case's criteria, and exits non-zero if the mean
+score is below THRESHOLD — so it can gate CI.
+
+    python evals/run_evals.py
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from agentx import get_chat_model
+{% if spec.framework == 'langgraph' %}
+from agentx.frameworks import run_agent
+from {{ pkg }}.agents import build_agents
+{% else %}
+from {{ pkg }}.agents import build_project_crew
+{% endif %}
+
+THRESHOLD = 0.6
+DATASET = Path(__file__).parent / "dataset.json"
+
+JUDGE_PROMPT = (
+    "You are a strict evaluator. Given a user INPUT, the agent's OUTPUT, and the "
+    "success CRITERIA, reply with ONLY a number between 0 and 1 (one decimal) for "
+    "how well OUTPUT satisfies CRITERIA.\n\n"
+    "INPUT: {input}\nOUTPUT: {output}\nCRITERIA: {criteria}\nSCORE:"
+)
+
+
+def _agent_reply(message: str) -> str:
+{% if spec.framework == 'langgraph' %}
+    agent = next(iter(build_agents().values()))
+    return run_agent(agent, message)
+{% else %}
+    return str(build_project_crew(message).kickoff())
+{% endif %}
+
+
+def _score(judge, case: dict, output: str) -> float:
+    text = judge.invoke(
+        JUDGE_PROMPT.format(input=case["input"], output=output, criteria=case.get("criteria", ""))
+    ).content
+    match = re.search(r"(\d(?:\.\d+)?)", text or "")
+    return max(0.0, min(1.0, float(match.group(1)))) if match else 0.0
+
+
+def main() -> int:
+    load_dotenv()
+    cases = json.loads(DATASET.read_text(encoding="utf-8"))
+    judge = get_chat_model()
+    scores = []
+    for case in cases:
+        output = _agent_reply(case["input"])
+        score = _score(judge, case, output)
+        scores.append(score)
+        print(f"[{score:.1f}] {case['input'][:60]}")
+    mean = sum(scores) / len(scores) if scores else 0.0
+    print(f"\nMean score: {mean:.2f} (threshold {THRESHOLD})")
+    return 0 if mean >= THRESHOLD else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentx/scaffold/templates/gitignore.j2

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.egg-info/
+.pytest_cache/
+.chroma/
+data/

agentx/scaffold/templates/mcp_servers.json.j2

@@ -0,0 +1,7 @@
+{
+  "filesystem": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+    "transport": "stdio"
+  }
+}

agentx/scaffold/templates/pkg/__init__.py.j2

@@ -0,0 +1,3 @@
+"""{{ spec.slug }} — generated by AgentX."""
+
+__version__ = "0.1.0"

agentx/scaffold/templates/pkg/agents.py.j2

@@ -0,0 +1,77 @@
+{% if spec.framework == 'langgraph' %}
+"""Agent definitions (LangGraph) — built dynamically from prompts.json."""
+from __future__ import annotations
+
+from agentx.frameworks import build_react_agent
+from agentx.tools import make_web_search_tool
+{% if spec.use_skills %}from agentx.skills import get_skill_registry
+{% endif %}
+from .config import MODEL, PROVIDER
+from .prompts import resolved_system_prompts
+{% if spec.use_rag %}from .rag import get_knowledge_tool
+{% endif %}
+{% if spec.use_mcp %}from .tools import get_mcp_tools
+{% endif %}
+
+
+def _build_tools():
+    tools = [make_web_search_tool()]
+{% if spec.use_rag %}
+    tools.append(get_knowledge_tool())
+{% endif %}
+{% if spec.use_mcp %}
+    tools.extend(get_mcp_tools())
+{% endif %}
+    return tools
+
+
+def build_agents():
+    """Return {name: compiled LangGraph agent} — one per entry in prompts.json."""
+    tools = _build_tools()
+{% if spec.use_skills %}
+    skills = get_skill_registry("data/skills").combined_instructions()
+{% else %}
+    skills = ""
+{% endif %}
+    agents = {}
+    for name, prompt in resolved_system_prompts().items():
+        if skills:
+            prompt = prompt + "\nApply these skills:\n" + skills
+        agents[name] = build_react_agent(
+            provider=PROVIDER, model=MODEL, tools=tools, system_prompt=prompt,
+        )
+    return agents
+{% else %}
+"""Agent + crew definitions (CrewAI) — built dynamically from prompts.json."""
+from __future__ import annotations
+
+from crewai import Task
+
+from agentx.frameworks import build_crew, build_crewai_agent
+from .config import MODEL, PROVIDER
+from .prompts import agents_meta, resolved_system_prompts
+
+
+def build_agents():
+    """Return {name: CrewAI Agent} — one per entry in prompts.json."""
+    prompts = resolved_system_prompts()
+    agents = {}
+    for name, meta in agents_meta().items():
+        agents[name] = build_crewai_agent(
+            role=meta.get("role", name),
+            goal=meta.get("goal", "Help the user accomplish their task accurately."),
+            backstory=prompts.get(name, ""),
+            provider=PROVIDER, model=MODEL,
+        )
+    return agents
+
+
+def build_project_crew(user_input: str):
+    """Assemble a sequential crew where each agent works the user's request."""
+    agents = build_agents()
+    tasks = [
+        Task(description=user_input, expected_output="A helpful, complete response.", agent=agent)
+        for agent in agents.values()
+    ]
+    return build_crew(list(agents.values()), tasks)
+{% endif %}

agentx/scaffold/templates/pkg/config.py.j2

@@ -0,0 +1,25 @@
+"""Typed configuration for {{ spec.slug }} (12-factor, pydantic-settings).
+
+Reads from environment / .env. Override at runtime, e.g. AGENTX_MODEL=gpt-4o.
+"""
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="AGENTX_", env_file=".env", extra="ignore")
+
+    provider: str = "{{ spec.provider }}"
+    model: str = "{{ model }}"
+    temperature: float = 0.3
+{% if spec.observability %}
+    telemetry: bool = True
+{% endif %}
+
+
+settings = Settings()
+
+# Convenience aliases used across the project.
+PROVIDER = settings.provider
+MODEL = settings.model

agentx/scaffold/templates/pkg/guardrails.py.j2

@@ -0,0 +1,21 @@
+"""Guardrails for {{ spec.slug }} — input/output validation + PII redaction.
+
+Customise BANNED_WORDS or compose your own guards. For jailbreak/moderation,
+wire in Guardrails-AI or NeMo Guardrails here.
+"""
+from __future__ import annotations
+
+from agentx.guardrails import GuardResult, apply_guards, default_input_guards, default_output_guards
+
+# Words/phrases to reject in user input (case-insensitive).
+BANNED_WORDS: list[str] = []
+
+
+def guard_input(text: str) -> GuardResult:
+    """Validate + lightly sanitise user input before it reaches the model."""
+    return apply_guards(text, default_input_guards(banned=BANNED_WORDS))
+
+
+def guard_output(text: str) -> GuardResult:
+    """Redact PII and cap length on model output before returning to the user."""
+    return apply_guards(text, default_output_guards(redact=True))

agentx/scaffold/templates/pkg/main.py.j2

@@ -0,0 +1,79 @@
+"""Entry point for {{ spec.slug }}."""
+from __future__ import annotations
+
+from dotenv import load_dotenv
+{% if spec.use_short_memory %}from .memory import session_memory
+{% endif %}
+{% if spec.observability %}from .observability import init_observability
+{% endif %}
+{% if spec.guardrails %}from .guardrails import guard_input, guard_output
+{% endif %}
+{% if spec.framework == 'langgraph' %}
+from agentx.frameworks import run_agent
+from .agents import build_agents
+
+
+def main() -> None:
+    load_dotenv()
+{% if spec.observability %}
+    init_observability()
+{% endif %}
+    agents = build_agents()
+    agent_name, agent = next(iter(agents.items()))
+    print("🧬 {{ spec.slug }} ready. Type 'quit' to exit.\n")
+    while True:
+        try:
+            user = input("you > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if user.lower() in {"quit", "exit"}:
+            break
+        if not user:
+            continue
+{% if spec.guardrails %}
+        user = guard_input(user).text
+{% endif %}
+{% if spec.use_short_memory %}
+        session_memory.add_user(user)
+{% endif %}
+        reply = run_agent(agent, user)
+{% if spec.guardrails %}
+        reply = guard_output(reply).text
+{% endif %}
+{% if spec.use_short_memory %}
+        session_memory.add_ai(reply)
+{% endif %}
+        print(f"\n{agent_name} > {reply}\n")
+{% else %}
+from .agents import build_project_crew
+
+
+def main() -> None:
+    load_dotenv()
+{% if spec.observability %}
+    init_observability()
+{% endif %}
+    print("🧬 {{ spec.slug }} (CrewAI). Type 'quit' to exit.\n")
+    while True:
+        try:
+            user = input("you > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if user.lower() in {"quit", "exit"}:
+            break
+        if not user:
+            continue
+{% if spec.guardrails %}
+        user = guard_input(user).text
+{% endif %}
+        crew = build_project_crew(user)
+        result = str(crew.kickoff())
+{% if spec.guardrails %}
+        result = guard_output(result).text
+{% endif %}
+        print(f"\ncrew > {result}\n")
+{% endif %}
+
+
+if __name__ == "__main__":
+    main()

agentx/scaffold/templates/pkg/memory.py.j2

@@ -0,0 +1,17 @@
+"""Memory for {{ spec.slug }} (mode: {{ spec.memory }})."""
+from __future__ import annotations
+
+{% if spec.use_short_memory %}
+from agentx.memory import ConversationMemory
+
+# Short-term, in-process rolling window of recent turns.
+session_memory = ConversationMemory(max_turns=12)
+{% endif %}
+{% if spec.use_long_memory %}
+from agentx.memory import LongTermMemory
+
+
+def long_term(session_id: str = "default") -> LongTermMemory:
+    """Persistent per-session memory (JSONL under data/memory/)."""
+    return LongTermMemory(f"data/memory/{session_id}.jsonl")
+{% endif %}

agentx/scaffold/templates/pkg/observability.py.j2

@@ -0,0 +1,17 @@
+"""Observability wiring for {{ spec.slug }}.
+
+OpenTelemetry GenAI tracing (+ optional Langfuse). Configure via env:
+  OTEL_EXPORTER_OTLP_ENDPOINT, LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY.
+Disable entirely with AGENTX_TELEMETRY=false.
+"""
+from __future__ import annotations
+
+from agentx.observability import get_callbacks, setup_tracing
+
+
+def init_observability(service_name: str = "{{ spec.slug }}") -> bool:
+    """Instrument tracing once at startup. Safe no-op if extras absent/disabled."""
+    return setup_tracing(service_name)
+
+
+__all__ = ["init_observability", "get_callbacks"]

agentx/scaffold/templates/pkg/prompts.py.j2

@@ -0,0 +1,45 @@
+"""Prompt loading for {{ spec.slug }}.
+
+Prompts live in `prompts.json` at the project root — the single source of truth
+for which agents exist and their system prompts. Edit that file directly, or use
+the CLI:
+
+    agentx prompt list
+    agentx prompt set <agent> --text "You are ..."
+    agentx prompt add <agent> --role "..." --goal "..." --text "..."
+
+A blank `system_prompt` is auto-derived from the agent's role + goal.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agentx.prompts import render_agent_system
+
+PROMPTS_FILE = Path(__file__).resolve().parents[2] / "prompts.json"
+
+
+def load_prompts() -> dict:
+    if PROMPTS_FILE.exists():
+        return json.loads(PROMPTS_FILE.read_text(encoding="utf-8"))
+    return {"with_rag": {{ spec.use_rag }}, "agents": {}}
+
+
+def resolved_system_prompts() -> dict[str, str]:
+    """Return {agent_name: system_prompt}, deriving blanks from role/goal."""
+    data = load_prompts()
+    with_rag = bool(data.get("with_rag", False))
+    out: dict[str, str] = {}
+    for name, meta in data.get("agents", {}).items():
+        explicit = (meta.get("system_prompt") or "").strip()
+        out[name] = explicit or render_agent_system(
+            role=meta.get("role", name),
+            goal=meta.get("goal", "Help the user accomplish their task accurately."),
+            with_rag=with_rag,
+        )
+    return out
+
+
+def agents_meta() -> dict[str, dict]:
+    return load_prompts().get("agents", {})

agentx/scaffold/templates/pkg/rag.py.j2

@@ -0,0 +1,37 @@
+"""RAG knowledge base for {{ spec.slug }}.
+
+Drop `.txt` / `.md` files into the project's `knowledge/` folder; they are
+chunked and indexed on first use. Uses Chroma when installed, else a built-in
+keyword retriever.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentx.rag import build_index_from_texts, make_retriever_tool
+
+_KNOWLEDGE_DIR = Path(__file__).resolve().parents[2] / "knowledge"
+_index = None
+
+
+def _load_texts() -> list[str]:
+    texts: list[str] = []
+    if _KNOWLEDGE_DIR.exists():
+        for fp in _KNOWLEDGE_DIR.glob("**/*"):
+            if fp.suffix.lower() in {".txt", ".md"}:
+                texts.append(fp.read_text(encoding="utf-8"))
+    return texts or [
+        "Placeholder knowledge base. Add .txt or .md files under the 'knowledge/' folder."
+    ]
+
+
+def get_index():
+    global _index
+    if _index is None:
+        _index = build_index_from_texts(_load_texts(), persist_dir=".chroma")
+    return _index
+
+
+def get_knowledge_tool():
+    """A LangChain tool that searches the knowledge base."""
+    return make_retriever_tool(get_index())

agentx/scaffold/templates/pkg/server.py.j2

@@ -0,0 +1,85 @@
+"""FastAPI server for {{ spec.slug }} — REST + SSE streaming.
+
+Run:  uv run uvicorn {{ pkg }}.server:app --reload --port 8000
+Endpoints: GET /health, POST /chat, GET /chat/stream?message=...
+"""
+from __future__ import annotations
+
+import json
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+load_dotenv()
+{% if spec.observability %}
+from .observability import init_observability
+
+init_observability()
+{% endif %}
+{% if spec.guardrails %}
+from .guardrails import guard_input, guard_output
+{% endif %}
+{% if spec.framework == 'langgraph' %}
+from agentx.frameworks import run_agent
+from .agents import build_agents
+
+_agent_cache = None
+
+
+def _reply(message: str) -> str:
+    global _agent_cache
+    if _agent_cache is None:
+        _agent_cache = next(iter(build_agents().values()))
+    return run_agent(_agent_cache, message)
+{% else %}
+from .agents import build_project_crew
+
+
+def _reply(message: str) -> str:
+    return str(build_project_crew(message).kickoff())
+{% endif %}
+
+app = FastAPI(title="{{ spec.slug }}", version="0.1.0")
+
+
+class ChatIn(BaseModel):
+    message: str
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok", "service": "{{ spec.slug }}"}
+
+
+@app.post("/chat")
+def chat(body: ChatIn) -> dict:
+    message = body.message
+{% if spec.guardrails %}
+    message = guard_input(message).text
+{% endif %}
+    reply = _reply(message)
+{% if spec.guardrails %}
+    reply = guard_output(reply).text
+{% endif %}
+    return {"reply": reply}
+
+
+@app.get("/chat/stream")
+def chat_stream(message: str) -> StreamingResponse:
+    """Server-Sent Events stream of the reply (token-chunked)."""
+{% if spec.guardrails %}
+    message = guard_input(message).text
+{% endif %}
+
+    def _events():
+        reply = _reply(message)
+{% if spec.guardrails %}
+        reply = guard_output(reply).text
+{% endif %}
+        for chunk in reply.split(" "):
+            yield f"data: {json.dumps({'token': chunk + ' '})}\n\n"
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(_events(), media_type="text/event-stream")

agentx/scaffold/templates/pkg/tools.py.j2

@@ -0,0 +1,16 @@
+"""MCP tools for {{ spec.slug }}.
+
+Configure servers in `mcp_servers.json` at the project root. Tools load lazily
+and degrade gracefully (returns [] if MCP isn't available).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentx.tools import load_mcp_tools
+
+_CONFIG = Path(__file__).resolve().parents[2] / "mcp_servers.json"
+
+
+def get_mcp_tools():
+    return load_mcp_tools(_CONFIG)

agentx/scaffold/templates/pyproject.toml.j2

@@ -0,0 +1,28 @@
+[project]
+name = "{{ spec.slug }}"
+version = "0.1.0"
+description = "Agentic app generated by AgentX ({{ spec.framework }} · {{ provider_label }})."
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+dependencies = [
+    "agentx-kit[{{ extras_str }}]>=0.1.0",
+    "python-dotenv>=1.0.0",
+    "ddgs>=9.0.0",
+]
+
+[project.scripts]
+{{ spec.slug }} = "{{ pkg }}.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ pkg }}"]
+
+{% if spec.agentx_local_path %}
+[tool.uv.sources]
+agentx-kit = { path = "{{ spec.agentx_local_path }}", editable = true }
+{% endif %}
+[tool.pytest.ini_options]
+pythonpath = ["src"]

agentx/scaffold/templates/skills_seed.json.j2

@@ -0,0 +1,6 @@
+{
+  "slug": "star-method",
+  "name": "STAR Method",
+  "description": "Structure answers as Situation, Task, Action, Result.",
+  "instructions": "When answering behavioural or experience questions, structure the response using the STAR method: Situation, Task, Action, Result. Be specific and quantify impact where possible."
+}

agentx/scaffold/wizard.py

@@ -0,0 +1,125 @@
+"""Interactive wizard — collects a ``ProjectSpec`` one option at a time.
+
+Uses ``questionary`` for arrow-key selection. Every prompt has a sensible
+default so power users can blast through with Enter.
+"""
+from __future__ import annotations
+
+import questionary
+
+from ..providers import all_specs, get_spec
+from .spec import AgentSpec, ProjectSpec
+
+_FRAMEWORKS = [
+    ("LangGraph (LangChain)", "langgraph"),
+    ("CrewAI", "crewai"),
+]
+_MEMORY = [
+    ("None", "none"),
+    ("Short-term (windowed buffer)", "short"),
+    ("Long-term (persistent JSONL)", "long"),
+    ("Both", "both"),
+]
+
+
+def _select(message: str, choices: list[tuple[str, str]], default_value: str) -> str:
+    options = [questionary.Choice(title=label, value=value) for label, value in choices]
+    default = next((o for o in options if o.value == default_value), options[0])
+    return questionary.select(message, choices=options, default=default).ask()
+
+
+def run_wizard(name: str | None = None) -> ProjectSpec | None:
+    """Run the interactive flow; returns a ProjectSpec, or None if cancelled."""
+    questionary.print("🧬  AgentX — new project\n", style="bold fg:cyan")
+
+    name = name or questionary.text("Project name:", default="my-agent").ask()
+    if not name:
+        return None
+
+    framework = _select("Agent framework:", _FRAMEWORKS, "langgraph")
+    if framework is None:
+        return None
+
+    # Provider + model
+    provider_choices = [
+        (f"{s.label}  ·  needs: {', '.join(s.env_vars) or 'no key (local)'}", s.id)
+        for s in all_specs()
+    ]
+    provider = _select("LLM provider:", provider_choices, "openai")
+    if provider is None:
+        return None
+    pspec = get_spec(provider)
+    model = questionary.text(
+        f"Model id ({pspec.label}):", default=pspec.default_model
+    ).ask() or pspec.default_model
+
+    # Agents
+    n_str = questionary.text("How many agents?", default="1").ask() or "1"
+    try:
+        n_agents = max(1, min(10, int(n_str)))
+    except ValueError:
+        n_agents = 1
+    agents: list[AgentSpec] = []
+    for i in range(n_agents):
+        questionary.print(f"\nAgent {i + 1} of {n_agents}", style="bold")
+        a_name = questionary.text("  name:", default=f"agent_{i + 1}" if n_agents > 1 else "assistant").ask()
+        a_role = questionary.text("  role:", default="Helpful Assistant").ask()
+        a_goal = questionary.text("  goal:", default="Help the user accomplish their task accurately.").ask()
+        a_prompt = questionary.text(
+            "  system prompt (optional — blank = auto from role/goal):", default="",
+            multiline=True,
+        ).ask()
+        agents.append(AgentSpec(
+            name=a_name or f"agent_{i + 1}",
+            role=a_role or "Assistant",
+            goal=a_goal or "Help the user.",
+            system_prompt=(a_prompt or "").strip(),
+        ))
+
+    # Capabilities — one by one
+    use_rag = questionary.confirm("Add a RAG module (knowledge base)?", default=False).ask()
+    memory = _select("Agent memory:", _MEMORY, "none")
+    use_mcp = questionary.confirm("Integrate MCP tools?", default=False).ask()
+    use_skills = questionary.confirm("Add a skills registry?", default=False).ask()
+    custom_prompts = questionary.confirm("Scaffold custom prompt templates (vs defaults)?", default=False).ask()
+
+    # Enterprise pack — bundle or pick individually
+    enterprise = questionary.confirm(
+        "Enable the enterprise pack (tracing, guardrails, FastAPI, Docker, CI, evals)?",
+        default=False,
+    ).ask()
+    if enterprise:
+        observability = guardrails = serve = docker = ci = evals = True
+    else:
+        observability = questionary.confirm("  • OpenTelemetry/Langfuse observability?", default=False).ask()
+        guardrails = questionary.confirm("  • Input/output guardrails?", default=False).ask()
+        serve = questionary.confirm("  • FastAPI server (REST + SSE)?", default=False).ask()
+        docker = questionary.confirm("  • Dockerfile + docker-compose?", default=False).ask()
+        ci = questionary.confirm("  • GitHub Actions CI?", default=False).ask()
+        evals = questionary.confirm("  • LLM-as-judge eval harness?", default=False).ask()
+
+    create_venv = questionary.confirm("Create a .venv with `uv` now?", default=True).ask()
+    run_sync = False
+    if create_venv:
+        run_sync = questionary.confirm("Install dependencies now (`uv sync`)? (needs network)", default=False).ask()
+
+    return ProjectSpec(
+        name=name,
+        framework=framework,
+        provider=provider,
+        model=model,
+        agents=agents,
+        use_rag=bool(use_rag),
+        memory=memory or "none",
+        use_mcp=bool(use_mcp),
+        use_skills=bool(use_skills),
+        prompt_style="custom" if custom_prompts else "default",
+        observability=bool(observability),
+        guardrails=bool(guardrails),
+        serve=bool(serve),
+        docker=bool(docker),
+        ci=bool(ci),
+        evals=bool(evals),
+        create_venv=bool(create_venv),
+        run_sync=bool(run_sync),
+    )