agentx-kit 0.5.0__tar.gz → 0.6.0__tar.gz

{agentx_kit-0.5.0 → agentx_kit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-kit
-Version: 0.5.0
+Version: 0.6.0
 Summary: An open-source, provider-agnostic agentic framework + interactive project scaffolder for LangChain and CrewAI. Pick your LLM provider, agents, RAG, memory, MCP tools and skills — generate a ready-to-run uv project.
 Project-URL: Homepage, https://github.com/muhammadyahiya/agentx-kit
 Project-URL: Repository, https://github.com/muhammadyahiya/agentx-kit
@@ -123,6 +123,53 @@ agentx new                 # interactive wizard → scaffolds a uv project
 > The PyPI distribution is **`agentx-kit`**; the import name and CLI are **`agentx`**
 > (`pip install agentx-kit` → `import agentx` / `agentx --help`).
 
+## 🚀 60-second walkthrough
+```bash
+# 1. Install
+pip install "agentx-kit[all]"
+
+# 2. See what you can target
+agentx providers                      # 9 LLM providers + the env vars each needs
+
+# 3. Scaffold a complete project from one line (no keys needed to generate)
+agentx new --yes --name my-bot \
+  --provider openai \
+  --prompt "You are a support agent that answers from our docs."
+
+# 4. Run it
+cd my-bot && cp .env.example .env      # add your API key
+uv sync && uv run my-bot
+
+# 5. Tune prompts live (tokens, cost, quality, optimize) — optional UI
+pip install "agentx-kit[dashboard]" && agentx dashboard
+
+# 6. Use it from Claude / Copilot / Codex
+claude mcp add agentx-kit -- agentx mcp
+```
+Prefer guided? Just run `agentx new` (interactive wizard) or
+`agentx new --enterprise` for the full production stack
+(tracing, guardrails, FastAPI, Docker, CI, evals, caching).
+
+### 🧭 Command cheat-sheet
+| Command | What it does |
+|---|---|
+| `agentx new` | Interactive wizard → scaffold a uv project |
+| `agentx new --yes [opts]` | Non-interactive scaffold (`--enterprise` for the full pack) |
+| `agentx providers` | List LLM providers + required env vars |
+| `agentx prompt list/set/add/remove` | Manage an existing project's prompts (`-d` opens the dashboard) |
+| `agentx dashboard` | Prompt observability + optimization UI (`[dashboard]` extra) |
+| `agentx cache stats / clear` | Inspect/clear the LLM response cache |
+| `agentx mcp` | Run as an MCP server for Claude/Copilot/Codex |
+| `agentx mcp --print-config` | Print the client config for those tools |
+| `agentx version` | Show the installed version |
+
+### ▶️ Try the demos (no API keys needed)
+```bash
+bash examples/demo_local.sh     # verify local setup end-to-end
+python examples/demo_mcp.py     # test the Claude/Copilot MCP path (real handshake)
+```
+See [`examples/`](examples/) for details.
+
 ## 📦 Installation
 
 ### From PyPI (recommended)

{agentx_kit-0.5.0 → agentx_kit-0.6.0}/README.md

@@ -19,6 +19,53 @@ agentx new                 # interactive wizard → scaffolds a uv project
 > The PyPI distribution is **`agentx-kit`**; the import name and CLI are **`agentx`**
 > (`pip install agentx-kit` → `import agentx` / `agentx --help`).
 
+## 🚀 60-second walkthrough
+```bash
+# 1. Install
+pip install "agentx-kit[all]"
+
+# 2. See what you can target
+agentx providers                      # 9 LLM providers + the env vars each needs
+
+# 3. Scaffold a complete project from one line (no keys needed to generate)
+agentx new --yes --name my-bot \
+  --provider openai \
+  --prompt "You are a support agent that answers from our docs."
+
+# 4. Run it
+cd my-bot && cp .env.example .env      # add your API key
+uv sync && uv run my-bot
+
+# 5. Tune prompts live (tokens, cost, quality, optimize) — optional UI
+pip install "agentx-kit[dashboard]" && agentx dashboard
+
+# 6. Use it from Claude / Copilot / Codex
+claude mcp add agentx-kit -- agentx mcp
+```
+Prefer guided? Just run `agentx new` (interactive wizard) or
+`agentx new --enterprise` for the full production stack
+(tracing, guardrails, FastAPI, Docker, CI, evals, caching).
+
+### 🧭 Command cheat-sheet
+| Command | What it does |
+|---|---|
+| `agentx new` | Interactive wizard → scaffold a uv project |
+| `agentx new --yes [opts]` | Non-interactive scaffold (`--enterprise` for the full pack) |
+| `agentx providers` | List LLM providers + required env vars |
+| `agentx prompt list/set/add/remove` | Manage an existing project's prompts (`-d` opens the dashboard) |
+| `agentx dashboard` | Prompt observability + optimization UI (`[dashboard]` extra) |
+| `agentx cache stats / clear` | Inspect/clear the LLM response cache |
+| `agentx mcp` | Run as an MCP server for Claude/Copilot/Codex |
+| `agentx mcp --print-config` | Print the client config for those tools |
+| `agentx version` | Show the installed version |
+
+### ▶️ Try the demos (no API keys needed)
+```bash
+bash examples/demo_local.sh     # verify local setup end-to-end
+python examples/demo_mcp.py     # test the Claude/Copilot MCP path (real handshake)
+```
+See [`examples/`](examples/) for details.
+
 ## 📦 Installation
 
 ### From PyPI (recommended)

agentx_kit-0.6.0/examples/README.md

@@ -0,0 +1,28 @@
+# AgentX-Kit demos
+
+Two runnable demos to confirm your setup — **no API keys required** (scaffolding
+and insights are offline; LLM calls are optional).
+
+## 1. Local setup test
+Verifies the install, lists providers, scaffolds a demo project, and exercises
+prompt insights + the response cache.
+
+```bash
+pip install "agentx-kit[all]"
+bash examples/demo_local.sh
+```
+
+## 2. MCP connector test (the Claude / Copilot / Codex path)
+Spawns `agentx mcp` over stdio, does a real MCP handshake, lists the tools, and
+scaffolds a complete project from a one-line problem statement — exactly what an
+assistant does when connected.
+
+```bash
+pip install "agentx-kit[connector]"
+python examples/demo_mcp.py
+```
+
+Then wire it into Claude for real:
+```bash
+claude mcp add agentx-kit -- agentx mcp
+```

agentx_kit-0.6.0/examples/demo_local.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# AgentX-Kit — local setup smoke test. No API keys required.
+# Verifies the install, lists providers, scaffolds a demo project, and exercises
+# the prompt-insights + cache so you know everything works end-to-end.
+#
+#   bash examples/demo_local.sh
+set -euo pipefail
+
+# Resolve the CLI: prefer `agentx` on PATH, else `python -m agentx.cli`.
+if command -v agentx >/dev/null 2>&1; then
+  AGENTX="agentx"
+else
+  AGENTX="python -m agentx.cli"
+fi
+echo "▶ using: $AGENTX"
+
+echo; echo "==> 1) version"
+$AGENTX version
+
+echo; echo "==> 2) providers (no keys needed to list)"
+$AGENTX providers
+
+WORK="$(mktemp -d)"; trap 'echo; echo "demo project left at: $WORK"' EXIT
+echo; echo "==> 3) scaffold a demo project (local Ollama provider, no key)"
+( cd "$WORK" && $AGENTX new --yes --name demo-agent --provider ollama \
+    --prompt "You are a helpful onboarding assistant." --no-venv )
+echo "files:"
+find "$WORK/demo-agent" -maxdepth 3 -type f | sed "s|$WORK/||" | sort
+
+echo; echo "==> 4) prompt insights (offline)"
+python - <<'PY'
+from agentx import analyze_prompt, count_tokens
+a = analyze_prompt("You are a support agent. Goal: answer in JSON. Do not invent policy.", "gpt-4o-mini")
+print(f"  quality={a.quality_score}/100  tokens={a.tokens}  suggestions={len(a.suggestions)}")
+PY
+
+echo; echo "==> 5) response cache stats"
+$AGENTX cache stats || true
+
+echo; echo "✅ Local setup looks good."
+echo "Next: cd $WORK/demo-agent && uv sync && uv run demo-agent"
+echo "      $AGENTX dashboard           # prompt observability UI (needs [dashboard] extra)"

agentx_kit-0.6.0/examples/demo_mcp.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+"""AgentX-Kit — MCP connector demo (the same path Claude / Copilot / Codex use).
+
+Spawns `agentx mcp` over stdio, performs a real MCP handshake, lists tools, and
+calls them to scaffold a complete project from a one-line problem statement —
+exactly what an MCP client (Claude) does. No API keys required (scaffolding is
+template generation).
+
+    pip install "agentx-kit[connector]"
+    python examples/demo_mcp.py
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import tempfile
+
+
+def _extract(result) -> dict:
+    """Pull a dict out of an MCP CallToolResult (structured or text content)."""
+    structured = getattr(result, "structuredContent", None)
+    if isinstance(structured, dict):
+        return structured.get("result", structured)
+    for block in getattr(result, "content", []) or []:
+        text = getattr(block, "text", None)
+        if text:
+            try:
+                return json.loads(text)
+            except json.JSONDecodeError:
+                return {"text": text}
+    return {}
+
+
+async def main() -> int:
+    try:
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+    except ImportError:
+        print("Install the connector extra first:  pip install 'agentx-kit[connector]'")
+        return 1
+
+    # Launch the same server Claude would (use this interpreter for portability).
+    params = StdioServerParameters(command=sys.executable, args=["-m", "agentx.cli", "mcp"])
+
+    print("▶ connecting to `agentx mcp` over stdio …")
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = await session.list_tools()
+            print("✓ connected. tools:", [t.name for t in tools.tools])
+
+            problem = "Build a customer-support agent that answers from our product docs and serves a REST API."
+            print(f"\n▶ recommend_project('{problem[:50]}…')")
+            rec = _extract(await session.call_tool("recommend_project", {"problem_statement": problem}))
+            print(f"  framework={rec.get('framework')}  features={rec.get('features')}")
+
+            out_dir = tempfile.mkdtemp(prefix="agentx-mcp-demo-")
+            print("\n▶ create_agent_project(…)")
+            res = _extract(await session.call_tool(
+                "create_agent_project",
+                {"problem_statement": problem, "output_dir": out_dir + "/support-bot"},
+            ))
+            if not res.get("ok"):
+                print("  ✗ failed:", res.get("error"))
+                return 1
+            print(f"  ✓ generated {len(res['file_tree'])} files at {res['target_dir']}")
+            print("    features:", res["features"])
+            print("    run:", res["next_steps"][-1])
+
+    print("\n✅ MCP connector works — Claude/Copilot/Codex can drive this exact flow.")
+    print("   Add it to Claude:  claude mcp add agentx-kit -- agentx mcp")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

{agentx_kit-0.5.0 → agentx_kit-0.6.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI distribution name (import name + CLI stay `agentx`; `agentx` was taken).
 name = "agentx-kit"
-version = "0.5.0"
+version = "0.6.0"
 description = "An open-source, provider-agnostic agentic framework + interactive project scaffolder for LangChain and CrewAI. Pick your LLM provider, agents, RAG, memory, MCP tools and skills — generate a ready-to-run uv project."
 readme = "README.md"
 requires-python = ">=3.10,<3.14"

{agentx_kit-0.5.0 → agentx_kit-0.6.0}/src/agentx/__init__.py

@@ -16,7 +16,7 @@ is enough to get started.
 """
 from __future__ import annotations
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 from .providers import (  # noqa: E402
     ProviderSpec,

{agentx_kit-0.5.0 → agentx_kit-0.6.0}/src/agentx/connector/build.py

@@ -74,10 +74,11 @@ def build_project_from_statement(
     # Collect a compact view for the calling LLM.
     tree = sorted(str(p.relative_to(root)) for p in root.glob("**/*") if p.is_file())
     pkg = spec.package
-    key_paths = [
-        "pyproject.toml", "prompts.json", "agentx.json",
-        f"src/{pkg}/main.py", f"src/{pkg}/agents.py", f"src/{pkg}/prompts.py",
-    ]
+    key_paths = ["pyproject.toml", "prompts.json", "agentx.json", f"src/{pkg}/main.py"]
+    if spec.framework == "langgraph":
+        key_paths += [f"src/{pkg}/graph.py", f"src/{pkg}/state.py", f"src/{pkg}/nodes.py"]
+    else:
+        key_paths += [f"src/{pkg}/crew.py", f"src/{pkg}/agents.py", f"src/{pkg}/tasks.py"]
     if spec.serve:
         key_paths.append(f"src/{pkg}/server.py")
     key_files = {}

{agentx_kit-0.5.0 → agentx_kit-0.6.0}/src/agentx/scaffold/generator.py

@@ -18,8 +18,8 @@ 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]] = [
+# (template, output-relative-path) — output paths use {pkg} placeholder.
+_COMMON_FILES: list[tuple[str, str]] = [
     ("pyproject.toml.j2", "pyproject.toml"),
     ("README.md.j2", "README.md"),
     ("env.example.j2", ".env.example"),
@@ -27,10 +27,24 @@ _FILE_PLAN: list[tuple[str, str]] = [
     ("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"),
 ]
 
+# A real LangGraph project: explicit state + nodes + graph + tool assembly.
+_LANGGRAPH_FILES: list[tuple[str, str]] = [
+    ("pkg/state.py.j2", "src/{pkg}/state.py"),
+    ("pkg/tools.py.j2", "src/{pkg}/tools.py"),
+    ("pkg/nodes.py.j2", "src/{pkg}/nodes.py"),
+    ("pkg/graph.py.j2", "src/{pkg}/graph.py"),
+]
+
+# A real CrewAI project: agents + tasks + crew.
+_CREWAI_FILES: list[tuple[str, str]] = [
+    ("pkg/agents.py.j2", "src/{pkg}/agents.py"),
+    ("pkg/tasks.py.j2", "src/{pkg}/tasks.py"),
+    ("pkg/crew.py.j2", "src/{pkg}/crew.py"),
+]
+
 
 @dataclass
 class GenerationResult:
@@ -70,6 +84,7 @@ def _context(spec: ProjectSpec) -> dict:
         "provider_env": list(provider_spec.env_vars),
         "extras": _extras(spec),
         "extras_str": ",".join(_extras(spec)),
+        "multi_agent": len(spec.agents) > 1,
     }
 
 
@@ -85,12 +100,13 @@ def _env() -> Environment:
 
 def _conditional_files(spec: ProjectSpec) -> list[tuple[str, str]]:
     plan: list[tuple[str, str]] = []
+    # Framework-specific core (real project structure).
+    plan += _LANGGRAPH_FILES if spec.framework == "langgraph" else _CREWAI_FILES
     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"))
@@ -156,7 +172,7 @@ def generate_project(spec: ProjectSpec, target_dir: str | Path, overwrite: bool
     written: list[Path] = []
     messages: list[str] = []
 
-    for template_name, out_rel in _FILE_PLAN + _conditional_files(spec):
+    for template_name, out_rel in _COMMON_FILES + _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)

agentx_kit-0.6.0/src/agentx/scaffold/templates/README.md.j2

@@ -0,0 +1,69 @@
+# {{ 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
+{% if spec.serve %}# API server:
+uv run uvicorn {{ pkg }}.server:app --reload
+{% endif %}
+```
+{% if spec.framework == 'langgraph' %}
+Uses LangGraph's dev server too: `uvx langgraph dev` (the compiled graph is
+`{{ pkg }}.graph:graph`).
+
+## Layout (LangGraph)
+```
+src/{{ pkg }}/
+├── config.py     # provider/model selection (pydantic-settings)
+├── prompts.py    # loads prompts.json (edit prompts there or via `agentx prompt`)
+├── state.py      # AgentState — the typed graph state (messages + reducers)
+├── tools.py      # tool assembly (web search{% if spec.use_rag %} + knowledge base{% endif %}{% if spec.use_mcp %} + MCP{% endif %})
+├── nodes.py      # graph nodes ({% if multi_agent %}supervisor + workers{% else %}the agent model call{% endif %})
+├── graph.py      # StateGraph workflow + compiled `graph` + run_text()
+{% if spec.use_rag %}├── rag.py        # knowledge base / retriever tool
+{% endif %}
+{% if spec.needs_memory %}├── memory.py     # conversation / long-term memory helpers
+{% endif %}
+{% if spec.serve %}├── server.py     # FastAPI (REST + SSE)
+{% endif %}
+└── main.py       # interactive REPL
+```
+{% else %}
+## Layout (CrewAI)
+```
+src/{{ pkg }}/
+├── config.py     # provider/model selection (pydantic-settings)
+├── prompts.py    # loads prompts.json
+├── agents.py     # CrewAI Agent definitions
+├── tasks.py      # Task definitions
+├── crew.py       # Crew assembly + run_text()
+{% if spec.serve %}├── server.py     # FastAPI (REST + SSE)
+{% endif %}
+└── main.py       # interactive REPL
+```
+{% endif %}
+{% 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_kit-0.5.0 → agentx_kit-0.6.0}/src/agentx/scaffold/templates/evals/run_evals.py.j2

@@ -17,10 +17,9 @@ 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
+from {{ pkg }}.graph import run_text
 {% else %}
-from {{ pkg }}.agents import build_project_crew
+from {{ pkg }}.crew import run_text
 {% endif %}
 
 THRESHOLD = 0.6
@@ -35,12 +34,7 @@ JUDGE_PROMPT = (
 
 
 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 %}
+    return run_text(message)
 
 
 def _score(judge, case: dict, output: str) -> float:

agentx_kit-0.6.0/src/agentx/scaffold/templates/pkg/agents.py.j2

@@ -0,0 +1,21 @@
+"""Agent definitions (CrewAI) for {{ spec.slug }} — built from prompts.json."""
+from __future__ import annotations
+
+from agentx.frameworks import build_crewai_agent
+from .config import MODEL, PROVIDER
+from .prompts import agents_meta, resolved_system_prompts
+
+
+def build_agents() -> dict:
+    """Return {name: CrewAI Agent} — one per entry in prompts.json."""
+    prompts = resolved_system_prompts()
+    agents: dict = {}
+    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

agentx_kit-0.6.0/src/agentx/scaffold/templates/pkg/crew.py.j2

@@ -0,0 +1,18 @@
+"""Crew assembly (CrewAI) for {{ spec.slug }}."""
+from __future__ import annotations
+
+from agentx.frameworks import build_crew
+from .agents import build_agents
+from .tasks import build_tasks
+
+
+def build_project_crew(user_input: str):
+    """Assemble a sequential crew of all agents for the user's request."""
+    agents = build_agents()
+    tasks = build_tasks(user_input, agents)
+    return build_crew(list(agents.values()), tasks)
+
+
+def run_text(message: str) -> str:
+    """Run the crew on a message and return the final text (used by main/server)."""
+    return str(build_project_crew(message).kickoff())

agentx_kit-0.6.0/src/agentx/scaffold/templates/pkg/graph.py.j2

@@ -0,0 +1,69 @@
+"""LangGraph workflow for {{ spec.slug }}.
+
+Exposes a module-level compiled ``graph`` (the LangGraph convention, also picked
+up by ``langgraph dev``) and a ``run_text`` helper for CLI/server use.
+"""
+from __future__ import annotations
+
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, START, StateGraph
+
+from .state import AgentState
+{% if not multi_agent %}
+from langgraph.prebuilt import ToolNode, tools_condition
+
+from .nodes import call_model
+from .tools import get_tools
+
+
+def build_graph():
+    """Build the ReAct agent graph: agent ⇄ tools, with checkpointed memory."""
+    builder = StateGraph(AgentState)
+    builder.add_node("agent", call_model)
+    builder.add_node("tools", ToolNode(get_tools()))
+
+    builder.add_edge(START, "agent")
+    # If the model asked for a tool, go run it; otherwise finish.
+    builder.add_conditional_edges("agent", tools_condition)
+    builder.add_edge("tools", "agent")
+
+    return builder.compile(checkpointer=MemorySaver())
+{% else %}
+from .nodes import WORKERS, make_worker, supervisor
+from .prompts import resolved_system_prompts
+
+
+def build_graph():
+    """Build a supervisor multi-agent graph: supervisor routes to workers."""
+    builder = StateGraph(AgentState)
+    builder.add_node("supervisor", supervisor)
+    for name, system_prompt in resolved_system_prompts().items():
+        builder.add_node(name, make_worker(name, system_prompt))
+
+    builder.add_edge(START, "supervisor")
+    # Supervisor decides the next worker, or ends.
+    builder.add_conditional_edges(
+        "supervisor",
+        lambda state: state.get("next", "FINISH"),
+        {**{name: name for name in WORKERS}, "FINISH": END},
+    )
+    # Every worker reports back to the supervisor.
+    for name in WORKERS:
+        builder.add_edge(name, "supervisor")
+
+    return builder.compile(checkpointer=MemorySaver())
+{% endif %}
+
+
+# Module-level compiled graph (import this, or run `langgraph dev`).
+graph = build_graph()
+
+
+def run_text(message: str, thread_id: str = "default") -> str:
+    """Invoke the graph with one user message; return the final text reply."""
+    result = graph.invoke(
+        {"messages": [{"role": "user", "content": message}]},
+        config={"configurable": {"thread_id": thread_id}},
+    )
+    messages = result.get("messages", [])
+    return getattr(messages[-1], "content", "") if messages else ""

agentx_kit-0.6.0/src/agentx/scaffold/templates/pkg/main.py.j2

@@ -0,0 +1,45 @@
+"""Entry point for {{ spec.slug }} — an interactive REPL over the agent graph."""
+from __future__ import annotations
+
+from dotenv import load_dotenv
+{% if spec.observability %}from .observability import init_observability
+{% endif %}
+{% if spec.guardrails %}from .guardrails import guard_input, guard_output
+{% endif %}
+{% if spec.use_cache %}from agentx.cache import enable_caching
+{% endif %}
+{% if spec.framework == 'langgraph' %}from .graph import run_text
+{% else %}from .crew import run_text
+{% endif %}
+
+
+def main() -> None:
+    load_dotenv()
+{% if spec.observability %}
+    init_observability()
+{% endif %}
+{% if spec.use_cache %}
+    enable_caching()   # cache LLM responses → lower cost & latency
+{% endif %}
+    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 %}
+        reply = run_text(user)
+{% if spec.guardrails %}
+        reply = guard_output(reply).text
+{% endif %}
+        print(f"\nbot > {reply}\n")
+
+
+if __name__ == "__main__":
+    main()