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

agentx_kit-0.5.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "agentx-kit",
+  "owner": { "name": "AgentX", "url": "https://github.com/muhammadyahiya/agentx-kit" },
+  "metadata": {
+    "description": "AgentX-Kit — scaffold agent projects from a prompt, in Claude Code.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "agentx-kit",
+      "source": "./integrations/claude-plugin",
+      "description": "Scaffold complete LangChain/CrewAI agent projects from a single problem statement via AgentX-Kit's MCP tools."
+    }
+  ]
+}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-kit
-Version: 0.3.0
+Version: 0.5.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
@@ -59,6 +59,8 @@ Provides-Extra: azure
 Requires-Dist: langchain-openai>=0.2.0; extra == 'azure'
 Provides-Extra: bedrock
 Requires-Dist: langchain-aws>=0.2.0; extra == 'bedrock'
+Provides-Extra: connector
+Requires-Dist: mcp>=1.2.0; extra == 'connector'
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.70.0; extra == 'crewai'
 Provides-Extra: dashboard
@@ -260,6 +262,72 @@ It gives you, live as you edit:
 Run it inside a generated AgentX project and it reads/writes that project's
 `prompts.json`; run it anywhere else for a free-form prompt scratchpad.
 
+## 🔌 Use as a connector (Claude / Copilot / Codex)
+AgentX-Kit ships an **MCP server**, so any MCP-capable assistant can scaffold a
+complete project from **a single prompt with your problem statement**.
+
+```bash
+pip install "agentx-kit[connector]"
+agentx mcp --print-config        # prints the client config below
+```
+
+Add it to your client (then restart it):
+```jsonc
+// Claude Desktop / Codex / Copilot — under "mcpServers"
+{ "mcpServers": { "agentx-kit": { "command": "agentx", "args": ["mcp"] } } }
+```
+```bash
+# Claude Code one-liner
+claude mcp add agentx-kit -- agentx mcp
+```
+
+Now just ask, in plain language:
+> *“Build a customer-support agent that answers from our product docs and serves a REST API.”*
+
+The assistant calls AgentX-Kit's tools and you get a complete, runnable project:
+- **`recommend_project(problem_statement)`** — suggests framework, provider, agent count, and features.
+- **`create_agent_project(problem_statement, …)`** — generates the project (infers RAG/serve/memory/etc. from the statement, or take explicit overrides / `enterprise=true`) and returns the file tree + key file contents + run steps.
+- **`list_providers`**, **`analyze_prompt`**, **`optimize_prompt`** — provider list + prompt insights.
+
+So from one sentence the assistant produces a pre-wired project (prompts already seeded from your use case), ready to `uv sync && uv run`.
+
+## 🧩 Editor & assistant integrations
+The same connector powers ready-made integrations (see [`integrations/`](integrations/)):
+
+- **VS Code extension** ([`integrations/vscode`](integrations/vscode)) — commands for
+  *New Agent Project*, *Open Prompt Dashboard*, *Add Prompt*, *Cache Stats*, and
+  *Register MCP Server for Copilot* (writes `.vscode/mcp.json`). Build with `vsce package`.
+- **GitHub Copilot** (agent mode) — add the MCP server via `.vscode/mcp.json`:
+  ```jsonc
+  { "servers": { "agentx-kit": { "command": "agentx", "args": ["mcp"] } } }
+  ```
+  (the VS Code command above writes this for you), then ask Copilot to build an agent.
+- **Claude Code plugin** ([`integrations/claude-plugin`](integrations/claude-plugin)):
+  ```text
+  /plugin marketplace add muhammadyahiya/agentx-kit
+  /plugin install agentx-kit@agentx-kit
+  /agentx-kit:new-agent a support agent that answers from our docs and serves an API
+  ```
+- **Claude Desktop / Codex** — add the connector config from `agentx mcp --print-config`.
+
+## 💾 Response caching (cost & latency saver)
+Caching is the top 2026 token-optimization lever. Turn on a **global LLM response
+cache** and every provider call is served from a local store on repeat — no code changes:
+
+```python
+from agentx import enable_caching, cache_stats
+enable_caching()                 # all get_chat_model(...) calls are cached
+...
+print(cache_stats())             # {'hit_rate': 0.6, 'tokens_saved': 12000, 'est_usd_saved': 0.024, ...}
+```
+```bash
+agentx cache stats               # hit rate + estimated tokens/$ saved
+agentx cache clear
+```
+Generated projects can enable it automatically (it's part of `--enterprise`), and the
+**dashboard's Trends tab shows live hit-rate and $ saved**. TTL-capable, SQLite-backed
+at `.agentx/llm_cache.sqlite`.
+
 ## 🏢 Enterprise pack
 Generate a production-shaped project with one flag — informed by a survey of
 CrewAI/LangGraph/create-llama/AgentStack/agno/pydantic-ai (see [RESEARCH.md](RESEARCH.md)):
@@ -309,6 +377,7 @@ llm = build_resilient_chat("openai", "gpt-4o-mini", fallbacks=[("anthropic", "cl
 | `observability` | `opentelemetry-*`, `openinference-*` | tracing |
 | `server` | `fastapi`, `uvicorn` | serving |
 | `dashboard` | `streamlit`, `tiktoken`, `pandas` | prompt observability dashboard |
+| `connector` | `mcp` | MCP server for Claude/Copilot/Codex |
 | `all` | everything above | kitchen sink |
 
 See [DESIGN.md](DESIGN.md) for the architecture and [RESEARCH.md](RESEARCH.md) for the competitive analysis behind these features.

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

@@ -158,6 +158,72 @@ It gives you, live as you edit:
 Run it inside a generated AgentX project and it reads/writes that project's
 `prompts.json`; run it anywhere else for a free-form prompt scratchpad.
 
+## 🔌 Use as a connector (Claude / Copilot / Codex)
+AgentX-Kit ships an **MCP server**, so any MCP-capable assistant can scaffold a
+complete project from **a single prompt with your problem statement**.
+
+```bash
+pip install "agentx-kit[connector]"
+agentx mcp --print-config        # prints the client config below
+```
+
+Add it to your client (then restart it):
+```jsonc
+// Claude Desktop / Codex / Copilot — under "mcpServers"
+{ "mcpServers": { "agentx-kit": { "command": "agentx", "args": ["mcp"] } } }
+```
+```bash
+# Claude Code one-liner
+claude mcp add agentx-kit -- agentx mcp
+```
+
+Now just ask, in plain language:
+> *“Build a customer-support agent that answers from our product docs and serves a REST API.”*
+
+The assistant calls AgentX-Kit's tools and you get a complete, runnable project:
+- **`recommend_project(problem_statement)`** — suggests framework, provider, agent count, and features.
+- **`create_agent_project(problem_statement, …)`** — generates the project (infers RAG/serve/memory/etc. from the statement, or take explicit overrides / `enterprise=true`) and returns the file tree + key file contents + run steps.
+- **`list_providers`**, **`analyze_prompt`**, **`optimize_prompt`** — provider list + prompt insights.
+
+So from one sentence the assistant produces a pre-wired project (prompts already seeded from your use case), ready to `uv sync && uv run`.
+
+## 🧩 Editor & assistant integrations
+The same connector powers ready-made integrations (see [`integrations/`](integrations/)):
+
+- **VS Code extension** ([`integrations/vscode`](integrations/vscode)) — commands for
+  *New Agent Project*, *Open Prompt Dashboard*, *Add Prompt*, *Cache Stats*, and
+  *Register MCP Server for Copilot* (writes `.vscode/mcp.json`). Build with `vsce package`.
+- **GitHub Copilot** (agent mode) — add the MCP server via `.vscode/mcp.json`:
+  ```jsonc
+  { "servers": { "agentx-kit": { "command": "agentx", "args": ["mcp"] } } }
+  ```
+  (the VS Code command above writes this for you), then ask Copilot to build an agent.
+- **Claude Code plugin** ([`integrations/claude-plugin`](integrations/claude-plugin)):
+  ```text
+  /plugin marketplace add muhammadyahiya/agentx-kit
+  /plugin install agentx-kit@agentx-kit
+  /agentx-kit:new-agent a support agent that answers from our docs and serves an API
+  ```
+- **Claude Desktop / Codex** — add the connector config from `agentx mcp --print-config`.
+
+## 💾 Response caching (cost & latency saver)
+Caching is the top 2026 token-optimization lever. Turn on a **global LLM response
+cache** and every provider call is served from a local store on repeat — no code changes:
+
+```python
+from agentx import enable_caching, cache_stats
+enable_caching()                 # all get_chat_model(...) calls are cached
+...
+print(cache_stats())             # {'hit_rate': 0.6, 'tokens_saved': 12000, 'est_usd_saved': 0.024, ...}
+```
+```bash
+agentx cache stats               # hit rate + estimated tokens/$ saved
+agentx cache clear
+```
+Generated projects can enable it automatically (it's part of `--enterprise`), and the
+**dashboard's Trends tab shows live hit-rate and $ saved**. TTL-capable, SQLite-backed
+at `.agentx/llm_cache.sqlite`.
+
 ## 🏢 Enterprise pack
 Generate a production-shaped project with one flag — informed by a survey of
 CrewAI/LangGraph/create-llama/AgentStack/agno/pydantic-ai (see [RESEARCH.md](RESEARCH.md)):
@@ -207,6 +273,7 @@ llm = build_resilient_chat("openai", "gpt-4o-mini", fallbacks=[("anthropic", "cl
 | `observability` | `opentelemetry-*`, `openinference-*` | tracing |
 | `server` | `fastapi`, `uvicorn` | serving |
 | `dashboard` | `streamlit`, `tiktoken`, `pandas` | prompt observability dashboard |
+| `connector` | `mcp` | MCP server for Claude/Copilot/Codex |
 | `all` | everything above | kitchen sink |
 
 See [DESIGN.md](DESIGN.md) for the architecture and [RESEARCH.md](RESEARCH.md) for the competitive analysis behind these features.

agentx_kit-0.5.0/integrations/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "agentx-kit",
+  "version": "0.1.0",
+  "description": "Scaffold complete provider-agnostic LangChain/CrewAI agent projects from a single problem statement, via AgentX-Kit's MCP tools.",
+  "author": { "name": "AgentX" },
+  "homepage": "https://github.com/muhammadyahiya/agentx-kit",
+  "license": "MIT",
+  "keywords": ["agents", "scaffold", "langchain", "crewai", "mcp"]
+}

agentx_kit-0.5.0/integrations/claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agentx-kit": {
+      "command": "agentx",
+      "args": ["mcp"]
+    }
+  }
+}

agentx_kit-0.5.0/integrations/claude-plugin/README.md

@@ -0,0 +1,29 @@
+# AgentX-Kit — Claude Code plugin
+
+Bundles AgentX-Kit's MCP server + a `/agentx-kit:new-agent` slash command so you
+can scaffold a complete agent project from a single problem statement inside
+Claude Code.
+
+## Prerequisite
+```bash
+pip install "agentx-kit[connector]"   # provides `agentx mcp`
+```
+
+## Install (from this repo's marketplace)
+```text
+/plugin marketplace add muhammadyahiya/agentx-kit
+/plugin install agentx-kit@agentx-kit
+```
+Then use it:
+```text
+/agentx-kit:new-agent a customer-support agent that answers from our docs and serves an API
+```
+
+## Or just add the MCP server (no plugin)
+```bash
+claude mcp add agentx-kit -- agentx mcp
+```
+
+The plugin ships:
+- `.mcp.json` — registers the `agentx-kit` MCP server (`agentx mcp`).
+- `commands/new-agent.md` — the `/agentx-kit:new-agent` workflow.

agentx_kit-0.5.0/integrations/claude-plugin/commands/new-agent.md

@@ -0,0 +1,14 @@
+---
+description: Scaffold a complete AgentX-Kit agent project from a problem statement
+argument-hint: <describe the agent / use case you want to build>
+---
+Build a complete, runnable agent project for this request using the AgentX-Kit MCP tools:
+
+**$ARGUMENTS**
+
+Steps:
+1. Call `recommend_project` with the problem statement and briefly show the recommended stack (framework, provider, agents, features) + rationale.
+2. Ask the user to confirm or adjust (provider/framework/enterprise), then call `create_agent_project` with the problem statement and any overrides.
+3. Report the target directory, the generated file tree, and the exact run steps it returns. Offer to open key files (main.py, agents.py, prompts.json).
+
+Keep it concise; the tools do the heavy lifting.

agentx_kit-0.5.0/integrations/vscode/.vscodeignore

@@ -0,0 +1,4 @@
+.vscode/**
+**/*.map
+.gitignore
+node_modules/**

agentx_kit-0.5.0/integrations/vscode/README.md

@@ -0,0 +1,34 @@
+# AgentX-Kit — VS Code extension
+
+Scaffold agent projects, open the prompt dashboard, and wire AgentX-Kit into
+**GitHub Copilot** (agent mode) — without leaving VS Code.
+
+## Prerequisite
+```bash
+pip install "agentx-kit[all]"   # provides the `agentx` CLI the extension calls
+```
+
+## Commands (⇧⌘P)
+- **AgentX: New Agent Project** — name + use case → `agentx new`
+- **AgentX: Open Prompt Dashboard** — `agentx dashboard`
+- **AgentX: Add Agent Prompt** — `agentx prompt set … -d`
+- **AgentX: Show Response-Cache Stats** — `agentx cache stats`
+- **AgentX: Register MCP Server for Copilot** — writes `.vscode/mcp.json` so Copilot
+  agent mode can call AgentX-Kit's tools (e.g. *"build a support agent over our docs"*).
+
+Set a custom CLI path with the `agentx.command` setting.
+
+## Build / install locally
+```bash
+npm install -g @vscode/vsce
+cd integrations/vscode
+vsce package           # -> agentx-kit-0.1.0.vsix
+code --install-extension agentx-kit-0.1.0.vsix
+```
+
+## Publish (needs a Marketplace publisher + PAT)
+```bash
+vsce login <publisher>
+vsce publish
+```
+See https://code.visualstudio.com/api/working-with-extensions/publishing-extension.

agentx_kit-0.5.0/integrations/vscode/extension.js

@@ -0,0 +1,87 @@
+// AgentX-Kit VS Code extension.
+// Thin wrapper over the `agentx` CLI + MCP registration for Copilot/agent mode.
+// Pure JS (no build step). Requires `pip install agentx-kit` on PATH.
+const vscode = require("vscode");
+const fs = require("fs");
+const path = require("path");
+
+function cli() {
+  return vscode.workspace.getConfiguration("agentx").get("command", "agentx");
+}
+
+function runInTerminal(name, commandLine) {
+  const term = vscode.window.createTerminal({ name });
+  term.show();
+  term.sendText(commandLine);
+}
+
+function workspaceRoot() {
+  const folders = vscode.workspace.workspaceFolders;
+  return folders && folders.length ? folders[0].uri.fsPath : process.cwd();
+}
+
+async function newProject() {
+  const name = await vscode.window.showInputBox({
+    prompt: "Project name", value: "my-agent",
+  });
+  if (!name) return;
+  const problem = await vscode.window.showInputBox({
+    prompt: "Describe the use case (optional — seeds the agent's prompt)", value: "",
+  });
+  const enterprise = await vscode.window.showQuickPick(["No", "Yes (tracing, guardrails, FastAPI, Docker, CI, evals, cache)"], {
+    placeHolder: "Enterprise pack?",
+  });
+  let cmd = `${cli()} new --yes --name ${JSON.stringify(name)}`;
+  if (problem) cmd += ` --prompt ${JSON.stringify(problem)}`;
+  if (enterprise && enterprise.startsWith("Yes")) cmd += " --enterprise";
+  runInTerminal("AgentX: new", cmd);
+}
+
+function dashboard() {
+  runInTerminal("AgentX: dashboard", `${cli()} dashboard`);
+}
+
+async function addPrompt() {
+  const agent = await vscode.window.showInputBox({ prompt: "Agent name", value: "assistant" });
+  if (!agent) return;
+  const text = await vscode.window.showInputBox({ prompt: "System prompt" });
+  if (text === undefined) return;
+  runInTerminal("AgentX: prompt", `${cli()} prompt set ${JSON.stringify(agent)} --text ${JSON.stringify(text)} -d`);
+}
+
+function cacheStats() {
+  runInTerminal("AgentX: cache", `${cli()} cache stats`);
+}
+
+// Write .vscode/mcp.json so GitHub Copilot (agent mode) / VS Code can use AgentX-Kit's MCP server.
+async function registerMcp() {
+  const root = workspaceRoot();
+  const dir = path.join(root, ".vscode");
+  const file = path.join(dir, "mcp.json");
+  let config = { servers: {} };
+  try {
+    if (fs.existsSync(file)) config = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) { /* start fresh on parse error */ }
+  config.servers = config.servers || {};
+  config.servers["agentx-kit"] = { command: cli(), args: ["mcp"] };
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(config, null, 2));
+  vscode.window.showInformationMessage(
+    "AgentX-Kit MCP server registered in .vscode/mcp.json. Open Copilot Chat (Agent mode) and ask it to build an agent from a problem statement."
+  );
+  const doc = await vscode.workspace.openTextDocument(file);
+  vscode.window.showTextDocument(doc);
+}
+
+function activate(context) {
+  const reg = (id, fn) => context.subscriptions.push(vscode.commands.registerCommand(id, fn));
+  reg("agentx.newProject", newProject);
+  reg("agentx.dashboard", dashboard);
+  reg("agentx.addPrompt", addPrompt);
+  reg("agentx.cacheStats", cacheStats);
+  reg("agentx.registerMcp", registerMcp);
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

agentx_kit-0.5.0/integrations/vscode/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agentx-kit",
+  "displayName": "AgentX-Kit",
+  "description": "Scaffold provider-agnostic LangChain/CrewAI agent projects, open the prompt dashboard, and wire AgentX-Kit into Copilot — from VS Code.",
+  "version": "0.1.0",
+  "publisher": "agentx",
+  "engines": { "vscode": "^1.85.0" },
+  "categories": ["Machine Learning", "Snippets", "Other"],
+  "keywords": ["ai", "agents", "llm", "langchain", "crewai", "mcp", "scaffold", "copilot"],
+  "icon": "icon.png",
+  "repository": { "type": "git", "url": "https://github.com/muhammadyahiya/agentx-kit" },
+  "license": "MIT",
+  "main": "./extension.js",
+  "activationEvents": [],
+  "contributes": {
+    "commands": [
+      { "command": "agentx.newProject", "title": "AgentX: New Agent Project" },
+      { "command": "agentx.dashboard", "title": "AgentX: Open Prompt Dashboard" },
+      { "command": "agentx.addPrompt", "title": "AgentX: Add Agent Prompt" },
+      { "command": "agentx.cacheStats", "title": "AgentX: Show Response-Cache Stats" },
+      { "command": "agentx.registerMcp", "title": "AgentX: Register MCP Server for Copilot" }
+    ],
+    "configuration": {
+      "title": "AgentX-Kit",
+      "properties": {
+        "agentx.command": {
+          "type": "string",
+          "default": "agentx",
+          "description": "Path to the agentx CLI (from `pip install agentx-kit`)."
+        }
+      }
+    }
+  }
+}

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

@@ -1,7 +1,7 @@
 [project]
 # PyPI distribution name (import name + CLI stay `agentx`; `agentx` was taken).
 name = "agentx-kit"
-version = "0.3.0"
+version = "0.5.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"
@@ -60,6 +60,7 @@ observability = [
 ]
 server = ["fastapi>=0.110.0", "uvicorn[standard]>=0.29.0", "sse-starlette>=2.0.0"]
 dashboard = ["streamlit>=1.40.0", "tiktoken>=0.7.0", "pandas>=2.0.0"]
+connector = ["mcp>=1.2.0"]
 
 # ---- Bundles ----
 all = [
@@ -73,6 +74,7 @@ all = [
     "openinference-instrumentation-langchain>=0.1.0",
     "fastapi>=0.110.0", "uvicorn[standard]>=0.29.0", "sse-starlette>=2.0.0",
     "streamlit>=1.40.0", "tiktoken>=0.7.0", "pandas>=2.0.0",
+    "mcp>=1.2.0",
 ]
 dev = ["pytest>=8.0.0", "pytest-cov>=5.0.0"]
 

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

@@ -16,7 +16,7 @@ is enough to get started.
 """
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 from .providers import (  # noqa: E402
     ProviderSpec,
@@ -39,6 +39,7 @@ from .insights import (  # noqa: E402
     estimate_cost,
     optimize_prompt,
 )
+from .cache import cache_stats, clear_cache, disable_caching, enable_caching  # noqa: E402
 
 __all__ = [
     "__version__",
@@ -63,4 +64,9 @@ __all__ = [
     "optimize_prompt",
     "count_tokens",
     "estimate_cost",
+    # response caching
+    "enable_caching",
+    "disable_caching",
+    "cache_stats",
+    "clear_cache",
 ]

agentx_kit-0.5.0/src/agentx/cache.py

@@ -0,0 +1,166 @@
+"""LLM response caching — cut cost & latency across all providers.
+
+Caching is the top token-optimization lever (2026): repeat/near-repeat calls are
+served from a local store instead of the model. This is an **exact** response
+cache implemented as a LangChain ``BaseCache`` and installed globally, so every
+``get_chat_model(...)`` call benefits automatically — no code changes.
+
+    from agentx.cache import enable_caching, cache_stats
+    enable_caching()                 # all subsequent LLM calls are cached
+    ...
+    print(cache_stats())             # hits, misses, est. tokens/$ saved
+
+Persistence is a small SQLite file (default ``.agentx/llm_cache.sqlite``) with an
+optional TTL. Stats track hit/miss and estimated tokens + USD saved (derived from
+cached completion sizes — see ``agentx.insights.tokens``).
+"""
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+_DEFAULT_PATH = ".agentx/llm_cache.sqlite"
+_lock = threading.Lock()
+
+
+def _key(prompt: str, llm_string: str) -> str:
+    return hashlib.sha256(f"{llm_string}\x00{prompt}".encode("utf-8")).hexdigest()
+
+
+def _model_from_llm_string(llm_string: str) -> str:
+    # llm_string is a serialized model descriptor; best-effort model name for costing.
+    for token in ("gpt-4o-mini", "gpt-4o", "gpt-4.1", "claude-3-5", "gemini-1.5", "llama"):
+        if token in llm_string:
+            return token
+    return "gpt-4o-mini"
+
+
+class AgentXCache:
+    """A LangChain ``BaseCache`` backed by SQLite, with TTL + savings stats.
+
+    Implements ``lookup``/``update`` (and ``aclear``) so it can be passed to
+    ``langchain_core.globals.set_llm_cache``.
+    """
+
+    def __init__(self, path: str | Path = _DEFAULT_PATH, ttl: int | None = None):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.ttl = ttl
+        self._init_db()
+
+    def _conn(self) -> sqlite3.Connection:
+        return sqlite3.connect(str(self.path))
+
+    def _init_db(self) -> None:
+        with _lock, self._conn() as c:
+            c.execute(
+                "CREATE TABLE IF NOT EXISTS cache "
+                "(key TEXT PRIMARY KEY, value TEXT, ts REAL, model TEXT, out_tokens INT)"
+            )
+            c.execute("CREATE TABLE IF NOT EXISTS stats (name TEXT PRIMARY KEY, val REAL)")
+            for name in ("hits", "misses", "tokens_saved"):
+                c.execute("INSERT OR IGNORE INTO stats(name, val) VALUES (?, 0)", (name,))
+
+    def _bump(self, conn: sqlite3.Connection, name: str, by: float = 1) -> None:
+        conn.execute("UPDATE stats SET val = val + ? WHERE name = ?", (by, name))
+
+    # ----- BaseCache interface -----
+    def lookup(self, prompt: str, llm_string: str) -> Any | None:
+        import warnings
+
+        from langchain_core.load import loads
+
+        key = _key(prompt, llm_string)
+        with _lock, self._conn() as c:
+            row = c.execute("SELECT value, ts, out_tokens FROM cache WHERE key = ?", (key,)).fetchone()
+            if not row:
+                self._bump(c, "misses")
+                return None
+            value, ts, out_tokens = row
+            if self.ttl is not None and (time.time() - ts) > self.ttl:
+                c.execute("DELETE FROM cache WHERE key = ?", (key,))
+                self._bump(c, "misses")
+                return None
+            self._bump(c, "hits")
+            self._bump(c, "tokens_saved", out_tokens or 0)
+        try:
+            # We wrote these values ourselves, so deserialization is trusted.
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                return loads(value)
+        except Exception:  # noqa: BLE001 - corrupt entry
+            return None
+
+    def update(self, prompt: str, llm_string: str, return_val: Any) -> None:
+        from langchain_core.load import dumps
+
+        from .insights.tokens import count_tokens
+
+        key = _key(prompt, llm_string)
+        model = _model_from_llm_string(llm_string)
+        text = ""
+        try:
+            text = " ".join(getattr(g, "text", "") or "" for g in return_val)
+        except Exception:  # noqa: BLE001
+            text = ""
+        out_tokens = count_tokens(text, model)
+        try:
+            payload = dumps(return_val)
+        except Exception:  # noqa: BLE001 - non-serializable result; skip caching
+            return
+        with _lock, self._conn() as c:
+            c.execute(
+                "INSERT OR REPLACE INTO cache(key, value, ts, model, out_tokens) VALUES (?, ?, ?, ?, ?)",
+                (key, payload, time.time(), model, out_tokens),
+            )
+
+    def clear(self, **kwargs: Any) -> None:
+        with _lock, self._conn() as c:
+            c.execute("DELETE FROM cache")
+            c.execute("UPDATE stats SET val = 0")
+
+    def stats(self) -> dict:
+        with _lock, self._conn() as c:
+            rows = dict(c.execute("SELECT name, val FROM stats").fetchall())
+            entries = c.execute("SELECT COUNT(*) FROM cache").fetchone()[0]
+        hits, misses = int(rows.get("hits", 0)), int(rows.get("misses", 0))
+        total = hits + misses
+        tokens_saved = int(rows.get("tokens_saved", 0))
+        # Conservative blended estimate: $0.002 / 1K output tokens saved.
+        cost_saved = round(tokens_saved / 1000 * 0.002, 6)
+        return {
+            "entries": entries,
+            "hits": hits,
+            "misses": misses,
+            "hit_rate": round(hits / total, 3) if total else 0.0,
+            "tokens_saved": tokens_saved,
+            "est_usd_saved": cost_saved,
+            "path": str(self.path),
+        }
+
+
+def enable_caching(path: str | Path = _DEFAULT_PATH, ttl: int | None = None) -> AgentXCache:
+    """Install a global LLM response cache. All providers benefit automatically."""
+    from langchain_core.globals import set_llm_cache
+
+    cache = AgentXCache(path, ttl=ttl)
+    set_llm_cache(cache)
+    return cache
+
+
+def disable_caching() -> None:
+    from langchain_core.globals import set_llm_cache
+
+    set_llm_cache(None)
+
+
+def cache_stats(path: str | Path = _DEFAULT_PATH) -> dict:
+    return AgentXCache(path).stats()
+
+
+def clear_cache(path: str | Path = _DEFAULT_PATH) -> None:
+    AgentXCache(path).clear()