agentx-kit 0.2.0__tar.gz

agentx_kit-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Publishes the package to PyPI via Trusted Publishing (OIDC) — no API token.
+# Triggers on a version tag push (e.g. `v0.1.0`) or manual dispatch.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the environment configured on the PyPI trusted publisher.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agentx-kit
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

agentx_kit-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+.ruff_cache/
+*.sqlite3
+data/
+chroma/
+.chroma/

agentx_kit-0.2.0/DESIGN.md

@@ -0,0 +1,98 @@
+# AgentX — High-Level Design
+
+AgentX is two things in one package:
+
+1. **A provider-agnostic agentic runtime library** (`agentx`) — a thin, batteries-included layer over **LangChain/LangGraph** and **CrewAI** that lets you talk to *any* LLM provider through one factory, and compose RAG, memory, MCP tools and skills.
+2. **An interactive project scaffolder** (`agentx new`) — a runtime wizard that asks you, one option at a time, which framework, provider, agents, RAG, memory, MCP and skills you want, then generates a **ready-to-run project in its own `uv` virtual environment (`.venv`)**.
+
+The generated project depends on `agentx` and is a working template you can run immediately.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                            agentx (CLI)                                 │
+│   agentx new   │   agentx providers   │   agentx version                    │
+└───────────────┬───────────────────────────────────────────────┬──────┘
+                │                                                 │
+        ┌───────▼─────────┐                              ┌────────▼────────┐
+        │  scaffold/      │  interactive wizard ──────►  │   generator     │
+        │  wizard.py      │  collects a ProjectSpec      │  renders Jinja  │
+        │  spec.py        │                              │  + `uv venv`    │
+        └─────────────────┘                              └────────┬────────┘
+                                                                   │ writes
+                                                                   ▼
+                                                   ┌───────────────────────────┐
+                                                   │  generated project (.venv) │
+                                                   │  main.py, agents.py, ...   │
+                                                   │  imports agentx        │
+                                                   └───────────────────────────┘
+
+        ── runtime library (imported by generated projects) ──
+        providers/  frameworks/  rag/  memory/  tools/  skills/  prompts/
+```
+
+## 1. Provider layer (`agentx/providers`)
+
+The crown jewel. A **registry** maps a provider id → a `ProviderSpec` describing:
+its display name, the pip extra to install, the env vars it needs, a sensible
+default model, and how to build a model object for **both** frameworks.
+
+| Provider id  | LangChain class                         | CrewAI model prefix     | Key env vars |
+|--------------|------------------------------------------|--------------------------|--------------|
+| `openai`     | `langchain_openai.ChatOpenAI`            | `openai/…`               | `OPENAI_API_KEY` |
+| `azure`      | `langchain_openai.AzureChatOpenAI`       | `azure/…`                | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` |
+| `openrouter` | `ChatOpenAI` (base_url=openrouter)       | `openrouter/…`           | `OPENROUTER_API_KEY` |
+| `anthropic`  | `langchain_anthropic.ChatAnthropic`      | `anthropic/…`            | `ANTHROPIC_API_KEY` |
+| `gemini`     | `langchain_google_genai.ChatGoogleGenerativeAI` | `gemini/…`        | `GOOGLE_API_KEY` |
+| `vertexai`   | `langchain_google_vertexai.ChatVertexAI` | `vertex_ai/…`            | `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT` |
+| `bedrock`    | `langchain_aws.ChatBedrockConverse`      | `bedrock/…`              | `AWS_*` / profile |
+| `groq`       | `langchain_groq.ChatGroq`                | `groq/…`                 | `GROQ_API_KEY` |
+| `ollama`     | `langchain_ollama.ChatOllama`            | `ollama/…` (+ base_url)  | — (local) |
+
+Two factory functions:
+- `get_chat_model(provider, model=None, **kw) -> BaseChatModel` (LangChain/LangGraph).
+- `get_crewai_llm(provider, model=None, **kw) -> crewai.LLM` (CrewAI; routes via LiteLLM).
+
+Imports are **lazy** — installing `agentx-kit[openai]` only is enough to use OpenAI; nothing else is imported until requested. A clear error tells you the exact extra to install.
+
+## 2. Frameworks (`agentx/frameworks`)
+
+- **LangGraph adapter** — `build_react_agent(...)` / a small `StateGraph` runner that wires a chat model + tools + memory into a runnable agent. Multi-agent = a graph of nodes.
+- **CrewAI adapter** — `build_agent(...)`, `build_crew(...)` helpers that accept the same provider/tool/memory inputs and return CrewAI `Agent`/`Crew` objects.
+
+Both consume the same building blocks so a project can switch frameworks with minimal change.
+
+## 3. Capabilities (optional, lazy)
+
+- **RAG** (`rag/`) — document loaders → `RecursiveCharacterTextSplitter` → vector store (Chroma, or an offline keyword fallback) → retriever. Exposed as a tool.
+- **Memory** (`memory/`) — short-term (windowed buffer) + long-term (persistent JSONL/SQLite) conversation memory.
+- **Tools / MCP** (`tools/`) — `load_mcp_tools(config)` via `langchain-mcp-adapters`; plus built-in tools (web search).
+- **Skills** (`skills/`) — a filesystem-backed skill registry whose instructions are injected into prompts (and optionally exposed as a lookup tool).
+- **Prompts** (`prompts/`) — reusable, override-able prompt templates.
+
+Every capability degrades gracefully: if its extra isn't installed, the feature is disabled with a helpful message rather than crashing.
+
+## 4. Scaffolder (`agentx/scaffold`)
+
+- `ProjectSpec` (pydantic) is the single source of truth for a generation run.
+- `wizard.py` collects it interactively (`questionary`), **one option at a time**:
+  project name → framework → provider → model → number & roles of agents →
+  RAG? → memory? → MCP? → skills? → prompt style → run `uv sync`?
+- `generator.py` renders **Jinja2 templates** into the target directory, writes a
+  provider/feature-aware `pyproject.toml` and `.env.example`, then runs
+  `uv venv` to create `.venv` (and optionally `uv sync`).
+- A programmatic `generate_project(spec, target_dir)` API makes the whole thing
+  testable and usable from other scripts (no TTY required).
+
+### Prompts are data, not code
+Every generated project is **prompt-file driven**: agent prompts live in a
+`prompts.json` that the generated `prompts.py` / `agents.py` load at runtime, and
+`build_agents()` iterates over that file. So adding an agent/prompt — at creation
+(`agentx new --prompt`) or afterward (`agentx prompt add|set|remove`, or editing the
+file) — changes the running project **without touching code**. `prompts_store.py`
+provides the safe read/modify/write helpers the CLI uses.
+
+## Design principles
+- **Provider-agnostic core, lazy provider imports** — install only what you use.
+- **One spec, two surfaces** — the same `ProjectSpec` drives interactive and programmatic generation.
+- **Generated code is readable** — templates produce idiomatic, commented code, not a black box.
+- **Graceful degradation** — optional capabilities never hard-crash the import.

agentx_kit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentx_kit-0.2.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: agentx-kit
+Version: 0.2.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
+Project-URL: Issues, https://github.com/muhammadyahiya/agentx-kit/issues
+Author: AgentX
+License: MIT
+License-File: LICENSE
+Keywords: agents,azure,bedrock,crewai,gemini,langchain,llm,mcp,openrouter,rag,scaffold,vertex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: <3.14,>=3.10
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: all
+Requires-Dist: chromadb>=0.5.0; extra == 'all'
+Requires-Dist: fastapi>=0.110.0; extra == 'all'
+Requires-Dist: langchain-anthropic>=0.2.0; extra == 'all'
+Requires-Dist: langchain-aws>=0.2.0; extra == 'all'
+Requires-Dist: langchain-community>=0.3.0; extra == 'all'
+Requires-Dist: langchain-google-genai>=2.0.0; extra == 'all'
+Requires-Dist: langchain-google-vertexai>=2.0.0; extra == 'all'
+Requires-Dist: langchain-groq>=0.2.0; extra == 'all'
+Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'all'
+Requires-Dist: langchain-ollama>=0.2.0; extra == 'all'
+Requires-Dist: langchain-openai>=0.2.0; extra == 'all'
+Requires-Dist: langchain-text-splitters>=0.3.0; extra == 'all'
+Requires-Dist: langchain>=0.3.0; extra == 'all'
+Requires-Dist: langgraph>=0.2.0; extra == 'all'
+Requires-Dist: mcp>=1.2.0; extra == 'all'
+Requires-Dist: openinference-instrumentation-langchain>=0.1.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
+Requires-Dist: sse-starlette>=2.0.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=0.2.0; extra == 'anthropic'
+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: crewai
+Requires-Dist: crewai>=0.70.0; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: langchain-google-genai>=2.0.0; extra == 'google'
+Provides-Extra: groq
+Requires-Dist: langchain-groq>=0.2.0; extra == 'groq'
+Provides-Extra: langgraph
+Requires-Dist: langchain>=0.3.0; extra == 'langgraph'
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Provides-Extra: mcp
+Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'mcp'
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Provides-Extra: observability
+Requires-Dist: openinference-instrumentation-langchain>=0.1.0; extra == 'observability'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'observability'
+Provides-Extra: ollama
+Requires-Dist: langchain-ollama>=0.2.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.2.0; extra == 'openai'
+Provides-Extra: openrouter
+Requires-Dist: langchain-openai>=0.2.0; extra == 'openrouter'
+Provides-Extra: rag
+Requires-Dist: chromadb>=0.5.0; extra == 'rag'
+Requires-Dist: langchain-community>=0.3.0; extra == 'rag'
+Requires-Dist: langchain-text-splitters>=0.3.0; extra == 'rag'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110.0; extra == 'server'
+Requires-Dist: sse-starlette>=2.0.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == 'server'
+Provides-Extra: vertex
+Requires-Dist: langchain-google-vertexai>=2.0.0; extra == 'vertex'
+Description-Content-Type: text/markdown
+
+# 🧬 AgentX-Kit
+
+[![PyPI](https://img.shields.io/pypi/v/agentx-kit.svg)](https://pypi.org/project/agentx-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/agentx-kit.svg)](https://pypi.org/project/agentx-kit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**A provider-agnostic agentic framework + interactive project scaffolder for LangChain & CrewAI.**
+
+Pick your LLM provider (OpenAI, Azure, OpenRouter, Anthropic, Gemini, Vertex AI,
+Bedrock, Groq, Ollama), choose your framework, agents, RAG, memory, MCP tools and
+skills — and AgentX-Kit generates a **ready-to-run project in its own `uv`
+virtual environment**.
+
+```bash
+pip install "agentx-kit[all]"
+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`).
+
+## 📦 Installation
+
+### From PyPI (recommended)
+```bash
+pip install agentx-kit                 # core: CLI + scaffolder + base abstractions
+pip install "agentx-kit[all]"          # everything
+```
+Each LLM provider is an **optional extra** so you only pull the SDKs you use:
+```bash
+pip install "agentx-kit[openai,langgraph]"        # OpenAI + LangGraph
+pip install "agentx-kit[bedrock,crewai,rag,mcp]"  # Bedrock + CrewAI + RAG + MCP
+```
+
+### Using `uv`
+```bash
+uv pip install "agentx-kit[all]"
+```
+
+### From GitHub (latest, unreleased)
+```bash
+pip install "agentx-kit[all] @ git+https://github.com/muhammadyahiya/agentx-kit.git"
+```
+
+### From a local clone (development)
+```bash
+git clone https://github.com/muhammadyahiya/agentx-kit.git
+cd agentx-kit
+uv venv && uv pip install -e ".[all,dev]"   # or: pip install -e ".[all,dev]"
+pytest -q
+```
+
+> Requires **Python 3.10–3.13** and (for the scaffolder's `.venv` creation)
+> [`uv`](https://docs.astral.sh/uv/).
+
+### Verify
+```bash
+agentx version
+agentx providers     # lists every provider + the env vars it needs
+```
+
+## Why
+- **One factory, every provider.** `get_chat_model("bedrock", ...)` or
+  `get_chat_model("openrouter", ...)` — same call, lazy imports, install only
+  the extras you use.
+- **Two frameworks.** LangChain/LangGraph *and* CrewAI from the same building blocks.
+- **Batteries included.** RAG, short/long-term memory, MCP tools, and a skills
+  registry — each optional and gracefully degrading.
+- **Scaffolder, not a black box.** The generated project is readable, idiomatic
+  code you own, pre-wired to your selections, in a fresh `.venv`.
+
+## Use as a library
+```python
+from agentx import get_chat_model, list_providers
+
+llm = get_chat_model("openai", "gpt-4o-mini")
+print(llm.invoke("Say hi in 3 words").content)
+
+for spec in list_providers():
+    print(spec.id, "→", spec.label)
+```
+
+CrewAI:
+```python
+from agentx import get_crewai_llm
+llm = get_crewai_llm("openrouter", "anthropic/claude-3.5-sonnet")
+```
+
+## Scaffold a project
+```bash
+agentx new                         # fully interactive
+agentx new --name my-bot --yes     # accept sensible defaults
+agentx providers                   # list providers + required env vars
+```
+
+The wizard asks, one option at a time:
+
+1. Project name & target directory
+2. Framework — **LangGraph** or **CrewAI**
+3. LLM **provider** and **model**
+4. Number of **agents** (and their roles)
+5. **RAG** module? (vector store)
+6. **Memory**? (short-term / long-term / both)
+7. **MCP tools**?
+8. **Skills** integration?
+9. **Prompt** style (defaults or scaffolded custom prompts)
+10. Create `.venv` and `uv sync` now?
+
+It then renders the project, writes a feature-aware `pyproject.toml` + `.env.example`,
+and runs `uv venv` to create `.venv`.
+
+## Prompts: add at creation, or any time after
+Prompts are **not baked into code** — every generated project keeps them in a
+`prompts.json` that `agents.py` loads dynamically. Add an entry and the project
+runs it on next start, **no code changes**.
+
+```bash
+# at creation
+agentx new --yes -n chatops --prompt "You are a senior DevOps engineer. Be terse."
+
+# after creation (run inside the project)
+agentx prompt list
+agentx prompt set assistant --text "You are an SRE. Prioritise reliability."
+agentx prompt add reviewer --role "Code Reviewer" --goal "Review diffs" \
+    --text "You review code for bugs and security."
+agentx prompt remove reviewer
+```
+
+`prompts.json`:
+```json
+{
+  "with_rag": false,
+  "agents": {
+    "assistant": {"role": "...", "goal": "...", "system_prompt": "You are ..."}
+  }
+}
+```
+A blank `system_prompt` is auto-derived from the agent's role + goal. You can also
+just open `prompts.json` in an editor — the CLI is a convenience, not a gate.
+
+## 🏢 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)):
+
+```bash
+agentx new --yes -n my-bot --enterprise        # everything below
+# or pick individually:
+agentx new --yes -n my-bot --observability --guardrails --serve --docker --ci --evals
+```
+
+What `--enterprise` adds to the generated project:
+- **Observability** — OpenTelemetry GenAI tracing + optional Langfuse (`observability.py`), opt-out via `AGENTX_TELEMETRY=false`.
+- **Guardrails** — input/output validation + PII redaction (`guardrails.py`).
+- **FastAPI server** — `server.py` with `/health`, `/chat`, and SSE `/chat/stream`.
+- **Docker** — `Dockerfile` + `docker-compose.yml` (+ `.dockerignore`).
+- **CI** — `.github/workflows/ci.yml` (lint + compile + tests, optional eval gate).
+- **Evals** — `evals/` LLM-as-judge harness runnable locally and in CI.
+- **Typed config** — `config.py` via `pydantic-settings` (12-factor).
+- **Manifest** — `agentx.json` declaring framework, provider, features (à la `langgraph.json`).
+
+These are also usable as a **library** in any project:
+```python
+from agentx import (
+    setup_tracing, get_callbacks,          # observability
+    build_resilient_chat,                  # retries + provider fallbacks
+    UsageLimits, UsageTracker,             # token/cost budgets
+    apply_guards, structured_model,        # guardrails + typed outputs
+)
+setup_tracing("my-service")
+llm = build_resilient_chat("openai", "gpt-4o-mini", fallbacks=[("anthropic", "claude-3-5-sonnet-latest")])
+```
+
+## Installation extras
+| Extra | Installs | For |
+|---|---|---|
+| `openai` / `azure` / `openrouter` | `langchain-openai` | OpenAI-compatible |
+| `anthropic` | `langchain-anthropic` | Claude |
+| `google` | `langchain-google-genai` | Gemini (AI Studio) |
+| `vertex` | `langchain-google-vertexai` | Vertex AI |
+| `bedrock` | `langchain-aws` | Amazon Bedrock |
+| `groq` | `langchain-groq` | Groq |
+| `ollama` | `langchain-ollama` | local |
+| `langgraph` | `langgraph`, `langchain` | LangGraph agents |
+| `crewai` | `crewai` | CrewAI crews |
+| `rag` | `langchain-community`, `chromadb` | RAG |
+| `mcp` | `langchain-mcp-adapters` | MCP tools |
+| `observability` | `opentelemetry-*`, `openinference-*` | tracing |
+| `server` | `fastapi`, `uvicorn` | serving |
+| `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.
+
+## License
+MIT

agentx_kit-0.2.0/README.md

@@ -0,0 +1,194 @@
+# 🧬 AgentX-Kit
+
+[![PyPI](https://img.shields.io/pypi/v/agentx-kit.svg)](https://pypi.org/project/agentx-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/agentx-kit.svg)](https://pypi.org/project/agentx-kit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**A provider-agnostic agentic framework + interactive project scaffolder for LangChain & CrewAI.**
+
+Pick your LLM provider (OpenAI, Azure, OpenRouter, Anthropic, Gemini, Vertex AI,
+Bedrock, Groq, Ollama), choose your framework, agents, RAG, memory, MCP tools and
+skills — and AgentX-Kit generates a **ready-to-run project in its own `uv`
+virtual environment**.
+
+```bash
+pip install "agentx-kit[all]"
+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`).
+
+## 📦 Installation
+
+### From PyPI (recommended)
+```bash
+pip install agentx-kit                 # core: CLI + scaffolder + base abstractions
+pip install "agentx-kit[all]"          # everything
+```
+Each LLM provider is an **optional extra** so you only pull the SDKs you use:
+```bash
+pip install "agentx-kit[openai,langgraph]"        # OpenAI + LangGraph
+pip install "agentx-kit[bedrock,crewai,rag,mcp]"  # Bedrock + CrewAI + RAG + MCP
+```
+
+### Using `uv`
+```bash
+uv pip install "agentx-kit[all]"
+```
+
+### From GitHub (latest, unreleased)
+```bash
+pip install "agentx-kit[all] @ git+https://github.com/muhammadyahiya/agentx-kit.git"
+```
+
+### From a local clone (development)
+```bash
+git clone https://github.com/muhammadyahiya/agentx-kit.git
+cd agentx-kit
+uv venv && uv pip install -e ".[all,dev]"   # or: pip install -e ".[all,dev]"
+pytest -q
+```
+
+> Requires **Python 3.10–3.13** and (for the scaffolder's `.venv` creation)
+> [`uv`](https://docs.astral.sh/uv/).
+
+### Verify
+```bash
+agentx version
+agentx providers     # lists every provider + the env vars it needs
+```
+
+## Why
+- **One factory, every provider.** `get_chat_model("bedrock", ...)` or
+  `get_chat_model("openrouter", ...)` — same call, lazy imports, install only
+  the extras you use.
+- **Two frameworks.** LangChain/LangGraph *and* CrewAI from the same building blocks.
+- **Batteries included.** RAG, short/long-term memory, MCP tools, and a skills
+  registry — each optional and gracefully degrading.
+- **Scaffolder, not a black box.** The generated project is readable, idiomatic
+  code you own, pre-wired to your selections, in a fresh `.venv`.
+
+## Use as a library
+```python
+from agentx import get_chat_model, list_providers
+
+llm = get_chat_model("openai", "gpt-4o-mini")
+print(llm.invoke("Say hi in 3 words").content)
+
+for spec in list_providers():
+    print(spec.id, "→", spec.label)
+```
+
+CrewAI:
+```python
+from agentx import get_crewai_llm
+llm = get_crewai_llm("openrouter", "anthropic/claude-3.5-sonnet")
+```
+
+## Scaffold a project
+```bash
+agentx new                         # fully interactive
+agentx new --name my-bot --yes     # accept sensible defaults
+agentx providers                   # list providers + required env vars
+```
+
+The wizard asks, one option at a time:
+
+1. Project name & target directory
+2. Framework — **LangGraph** or **CrewAI**
+3. LLM **provider** and **model**
+4. Number of **agents** (and their roles)
+5. **RAG** module? (vector store)
+6. **Memory**? (short-term / long-term / both)
+7. **MCP tools**?
+8. **Skills** integration?
+9. **Prompt** style (defaults or scaffolded custom prompts)
+10. Create `.venv` and `uv sync` now?
+
+It then renders the project, writes a feature-aware `pyproject.toml` + `.env.example`,
+and runs `uv venv` to create `.venv`.
+
+## Prompts: add at creation, or any time after
+Prompts are **not baked into code** — every generated project keeps them in a
+`prompts.json` that `agents.py` loads dynamically. Add an entry and the project
+runs it on next start, **no code changes**.
+
+```bash
+# at creation
+agentx new --yes -n chatops --prompt "You are a senior DevOps engineer. Be terse."
+
+# after creation (run inside the project)
+agentx prompt list
+agentx prompt set assistant --text "You are an SRE. Prioritise reliability."
+agentx prompt add reviewer --role "Code Reviewer" --goal "Review diffs" \
+    --text "You review code for bugs and security."
+agentx prompt remove reviewer
+```
+
+`prompts.json`:
+```json
+{
+  "with_rag": false,
+  "agents": {
+    "assistant": {"role": "...", "goal": "...", "system_prompt": "You are ..."}
+  }
+}
+```
+A blank `system_prompt` is auto-derived from the agent's role + goal. You can also
+just open `prompts.json` in an editor — the CLI is a convenience, not a gate.
+
+## 🏢 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)):
+
+```bash
+agentx new --yes -n my-bot --enterprise        # everything below
+# or pick individually:
+agentx new --yes -n my-bot --observability --guardrails --serve --docker --ci --evals
+```
+
+What `--enterprise` adds to the generated project:
+- **Observability** — OpenTelemetry GenAI tracing + optional Langfuse (`observability.py`), opt-out via `AGENTX_TELEMETRY=false`.
+- **Guardrails** — input/output validation + PII redaction (`guardrails.py`).
+- **FastAPI server** — `server.py` with `/health`, `/chat`, and SSE `/chat/stream`.
+- **Docker** — `Dockerfile` + `docker-compose.yml` (+ `.dockerignore`).
+- **CI** — `.github/workflows/ci.yml` (lint + compile + tests, optional eval gate).
+- **Evals** — `evals/` LLM-as-judge harness runnable locally and in CI.
+- **Typed config** — `config.py` via `pydantic-settings` (12-factor).
+- **Manifest** — `agentx.json` declaring framework, provider, features (à la `langgraph.json`).
+
+These are also usable as a **library** in any project:
+```python
+from agentx import (
+    setup_tracing, get_callbacks,          # observability
+    build_resilient_chat,                  # retries + provider fallbacks
+    UsageLimits, UsageTracker,             # token/cost budgets
+    apply_guards, structured_model,        # guardrails + typed outputs
+)
+setup_tracing("my-service")
+llm = build_resilient_chat("openai", "gpt-4o-mini", fallbacks=[("anthropic", "claude-3-5-sonnet-latest")])
+```
+
+## Installation extras
+| Extra | Installs | For |
+|---|---|---|
+| `openai` / `azure` / `openrouter` | `langchain-openai` | OpenAI-compatible |
+| `anthropic` | `langchain-anthropic` | Claude |
+| `google` | `langchain-google-genai` | Gemini (AI Studio) |
+| `vertex` | `langchain-google-vertexai` | Vertex AI |
+| `bedrock` | `langchain-aws` | Amazon Bedrock |
+| `groq` | `langchain-groq` | Groq |
+| `ollama` | `langchain-ollama` | local |
+| `langgraph` | `langgraph`, `langchain` | LangGraph agents |
+| `crewai` | `crewai` | CrewAI crews |
+| `rag` | `langchain-community`, `chromadb` | RAG |
+| `mcp` | `langchain-mcp-adapters` | MCP tools |
+| `observability` | `opentelemetry-*`, `openinference-*` | tracing |
+| `server` | `fastapi`, `uvicorn` | serving |
+| `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.
+
+## License
+MIT