Metadata-Version: 2.4
Name: cortex-agent-framework
Version: 1.5.0
Summary: Fan-Out/Fan-In agentic orchestration framework with multi-provider LLM support and MCP tool integration.
Author-email: Kriti Ranjan Das <kritiranjan.das@gmail.com>
Maintainer-email: Kriti Ranjan Das <kritiranjan.das@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Kriti Ranjan Das
        
        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.
        
Project-URL: Homepage, https://github.com/kritird/cortex-agent-framework
Project-URL: Repository, https://github.com/kritird/cortex-agent-framework
Project-URL: Issues, https://github.com/kritird/cortex-agent-framework/issues
Project-URL: Documentation, https://github.com/kritird/cortex-agent-framework/tree/main/docs
Project-URL: Changelog, https://github.com/kritird/cortex-agent-framework/blob/main/CHANGELOG.md
Keywords: agent,agentic,llm,orchestration,anthropic,claude,mcp,model-context-protocol,ai,framework,fan-out-fan-in,task-graph
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: aiofiles>=23.0
Requires-Dist: boto3>=1.34
Requires-Dist: click>=8.1
Requires-Dist: redis>=5.0
Requires-Dist: aiosqlite>=0.20
Requires-Dist: cryptography>=42.0
Requires-Dist: opentelemetry-sdk>=1.24
Requires-Dist: opentelemetry-exporter-otlp>=1.24
Requires-Dist: jinja2>=3.1
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://kritird.github.io/Cortex-Agent-Framework/">
    <img src="https://img.shields.io/badge/🌐_Full_docs_%26_landing_page-06b6d4?style=for-the-badge&labelColor=07070f" alt="Full docs & landing page" />
  </a>
</p>

> **📖 Looking for the full docs, feature showcase, and use cases?**
> Visit the **[Cortex landing page →](https://kritird.github.io/Cortex-Agent-Framework/)**

---

<table>
  <tr>
    <td width="150"><img src="logo/cortex-logo-new-v1.svg" alt="Cortex Agent Framework" width="130" /></td>
    <td>
      <h1>Cortex Agent Framework</h1>
      <strong>One YAML file. One method call. A production AI agent.</strong><br/>
      Stop rebuilding the same agent plumbing. Define it once, deploy anywhere, let it learn.
    </td>
  </tr>
</table>

<p align="center">
  <a href="https://pypi.org/project/cortex-agent-framework/"><img src="https://img.shields.io/pypi/v/cortex-agent-framework.svg" alt="PyPI version" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+" /></a>
  <img src="https://img.shields.io/badge/LLMs-8_providers_+_local-green.svg" alt="8 LLM providers + local" />
  <img src="https://img.shields.io/badge/MCP-native-purple.svg" alt="MCP native" />
</p>

<p align="center">
  <a href="docs/OVERVIEW.md">Overview</a> •
  <a href="docs/ARCHITECTURE.md">Architecture</a> •
  <a href="docs/FEATURES.md">Features</a> •
  <a href="docs/GETTING_STARTED.md">Getting Started</a> •
  <a href="docs/USE_CASES.md">Use Cases</a> •
  <a href="docs/CONFIGURATION.md">Config</a> •
  <a href="docs/CLI.md">CLI</a> •
  <a href="docs/DEPLOYMENT.md">Deployment</a> •
  <a href="docs/FAQ.md">FAQ</a>
</p>

---

## The problem

Every AI team builds the same stack: task decomposition, parallel tool execution, streaming, retries, session management, quality scoring, multi-provider routing, deployment. Most teams rebuild it two or three times before shipping.

**Cortex is that stack.** Pre-built. Battle-tested. Driven by config, not code.

---

## 3 commands. A running agent.

```bash
pip install cortex-agent-framework
cortex setup            # visual wizard at localhost:7799
cortex publish ui       # chat UI at localhost:8090
```

Or invoke the agent directly from the terminal:

```bash
cortex run "Research the latest vector DB benchmarks"
cortex chat                                            # interactive REPL
```

You now have a working agent with a professional web interface, file upload support, streaming responses, and persistent chat history. No frontend to build. No backend to wire. No infrastructure to manage.

---

## Define your agent in YAML. Run it in Python.

```yaml
agent:
  name: ResearchAgent
  description: Searches the web and writes reports

llm_access:
  default:
    provider: anthropic
    model: claude-sonnet-4-5
    api_key_env_var: ANTHROPIC_API_KEY

task_types:
  - name: web_research
    capability_hint: web_search
    output_format: md
  - name: write_report
    capability_hint: document_generation
    depends_on: [web_research]
```

```python
from cortex.framework import CortexFramework

framework = CortexFramework("cortex.yaml")
await framework.initialize()

result = await framework.run_session(
    user_id="user_1",
    request="Research the latest vector DB benchmarks and write a report",
)
print(result.response)
```

Fan-out, tool calls, dependency resolution, synthesis, validation — all handled.

---

## Or define it in Python — code-first agents

Prefer code to config? Build the entire agent with `CortexBuilder` and wire in
**code nodes** — plain Python functions as graph nodes, LangGraph-style. No
YAML file, no decomposition LLM call: the graph runs exactly as you wrote it.

```python
from cortex import CortexBuilder, CortexFramework

agent = CortexBuilder("ResearchAgent", "Searches the web and writes reports")
agent.llm("anthropic", model="claude-sonnet-4-5", api_key_env="ANTHROPIC_API_KEY")
agent.tool_server("brave", url="http://localhost:9000/sse")

@agent.node()
async def web_research(ctx):
    return await ctx.call_tool("brave", "search", query=ctx.request)

@agent.node(depends_on=["web_research"])
async def write_report(ctx):
    return await ctx.llm(f"Write a report from:\n{ctx.deps['web_research']}")

framework = CortexFramework(config=agent.build())
await framework.initialize()

result = await framework.run_session("user_1", "Research vector DB benchmarks")
print(result.response)                       # synthesised answer
print(result.node_outputs["write_report"])   # raw output of one node
```

Registering a code node flips the agent to **static execution** — the DAG you
declared is the plan. Each node receives a `TaskContext` with `ctx.request`,
`ctx.deps` (upstream node outputs), `ctx.llm()`, and `ctx.call_tool()`. You
still get the wave engine, validation gate, retries, streaming, and session
persistence — Cortex just skips the planner. Mix `.task()` (LLM-routed) and
`.node()` (Python) freely. See **[Getting Started](docs/GETTING_STARTED.md)**.

---

## Why teams choose Cortex

### Skip months of framework engineering

The orchestration, parallelism, tool integration, streaming, retries, validation, session persistence, and deployment pipeline — it's all in the box. Your Python code stays a thin wrapper. The agent's behavior lives in `cortex.yaml`, versioned, diffable, reviewable.

### Multi-agent composition for free

Any Cortex agent becomes an MCP server in one command. Other agents consume it as a tool. That's the entire inter-agent protocol — standard MCP, nothing custom.

```
Orchestrator → Research Agent (MCP :8081) → brave-search, wikipedia
             → Code Review Agent (MCP :8082) → github, filesystem
             → Writing Agent (MCP :8083) → document-gen
```

Each agent scales, deploys, and configures independently. Compose them by adding YAML lines.

### Built-in quality gates

Every response passes through a **Validation Agent** that scores intent match, completeness, and coherence. You set a floor (default: 0.75); responses below it are flagged and remediated. Bad intermediate outputs are retried with feedback before the pipeline moves on.

Catch regressions before users do, not after.

### Your agent gets smarter over time

The **Learning Engine** observes task patterns across sessions. When patterns recur, it stages a **delta proposal** — a concrete config change you review with `cortex delta review` and apply in one command. The agent doesn't silently drift; it surfaces what it learned and asks for approval.

---

## What's in the box

| | |
|---|---|
| **8 cloud LLM providers + local** | Anthropic, OpenAI, Gemini, Grok, Mistral, DeepSeek, AWS Bedrock, Azure AI — plus local Ollama / LM Studio / vLLM with a Gemma 4 quickstart |
| **Code-first agents** | Build the whole agent in Python with `CortexBuilder`; `@node` decorator turns plain functions into graph nodes — static DAG, no decomposition LLM call |
| **Fan-out / fan-in** | LLM-generated DAG with parallel execution; independent tasks run simultaneously |
| **Intent Gate** | Cheap heuristic + LLM cascade routes chat-shaped turns directly to a streaming reply; only task-shaped turns decompose |
| **`interaction_mode`** | One agent, two contracts: `interactive` for chat / CLI, `rpc` for MCP / automation — never blocks on clarifications |
| **MCP-native tools** | First-class SSE, stdio, and streamable-HTTP MCP tool servers |
| **Multi-agent mesh** | Publish any agent as an MCP server — compose specialist agents into an orchestrator |
| **Ant Colony** | Orchestrator self-spawns specialist Cortex agents as MCP servers at runtime; supervised, health-checked, auto-restarted |
| **Identity & delegation** | First-class `Principal` model — human, system, or agent-to-agent calls with full delegation chains in audit logs |
| **Quality validation** | Every response scored and gated; per-task validation inside the execution loop |
| **Autonomic learning** | Signal-gated end-of-session evolution — complexity + validation thresholds trigger staging; distinct-principal confirmation gates promotion |
| **Blueprints** | Reusable workflow knowledge loaded into context; refined automatically when a session clears the validation threshold, seeded as drafts the moment a new task pattern is staged |
| **Streaming** | Typed event classes (`StatusEvent`, `ResultEvent`, `ClarificationEvent`) for any UI |
| **Smart synthesis** | Keyword-grep excerpts + concurrent per-file LLM summaries; large results written to disk as a `file` ResultEvent |
| **Native app control** | Launch and drive desktop applications via AppleScript (macOS), PowerShell + UIA (Windows), or a screenshot vision loop — every mutating action gated by HITL |
| **Built-in browser automation** | Playwright MCP starts internally — chromium / firefox / webkit with persistent session state so logins survive runs. No tool-server wiring required |
| **Polyglot code sandbox** | `# LANGUAGE:` header dispatches to Python, Node, TypeScript, Deno, shell, Ruby, Go, Rust, C, Java, or Kotlin — with per-ecosystem package install (`npm`, `gem`, `go get`) |
| **Per-task LLM routing** | Route decomposition to a fast model, synthesis to flagship |
| **Auto-tuned LLM concurrency** | `max_parallel_llm_calls` derives from your provider+model (1 for local Ollama, 8 for Haiku, 4 for Opus) and self-tunes at runtime via `AdaptiveLLMGate` — no wizard knob to guess |
| **Session persistence** | Memory / SQLite / Redis with WAL replay and resumable sessions |
| **Built-in chat UI** | Web frontend with file uploads, streaming, and conversation history |
| **4 deploy targets** | `publish docker`, `publish package`, `publish mcp`, `publish ui` |
| **Visual setup wizard** | Configure everything from a browser — `cortex setup` |
| **Full CLI** | `cortex run`, `cortex chat`, `cortex sessions`, `cortex stats`, `cortex providers`, `cortex storage`, `cortex blueprints`, `cortex mcps` — manage every aspect of the framework without writing Python |
| **Security** | Input sanitisation, credential scrubbing, sandboxed code execution, MCP output guard |
| **Observability** | OpenTelemetry, audit logs, anomaly detection, token budgets |

---

## How Cortex compares

| Capability | Cortex | Typical agent frameworks |
|---|---|---|
| **Configuration** | Single `cortex.yaml` *or* a Python `CortexBuilder` | Scattered code, env vars, multiple config files |
| **Task orchestration** | LLM-generated DAG *or* a hand-authored static DAG of code nodes | Sequential chain or hand-coded state machine |
| **Tool protocol** | Native MCP (SSE, stdio, streamable-HTTP) | Custom tool wrappers per integration |
| **Multi-agent** | Any agent becomes an MCP tool in one command | Bespoke inter-agent protocols |
| **Quality gates** | Built-in validation with scoring + remediation | Manual testing or nothing |
| **Learning** | Delta proposals + blueprints with human review | Prompt tweaking by hand |
| **LLM providers** | 8 built-in, swap via config | Usually 1-2, hard-coded |
| **Deployment** | 4 targets, one command each | Write your own Dockerfile |

---

## Who is Cortex for?

| You are... | Cortex gives you... |
|---|---|
| **Startup founder** shipping an AI product | A production agent runtime in an afternoon — skip 3-6 months of plumbing |
| **Platform team** at a larger company | A governed agent runtime with audit trails, quality gates, and per-user isolation |
| **Enterprise architect** | Multi-agent meshes with independent scaling and compliance-friendly history encryption |
| **Solo developer** | Prototype to production with one YAML file — or skip YAML entirely and build the agent in Python |
| **LangGraph / framework refugee** | Code-first agents with `@node` functions and a static DAG — keep Cortex's wave engine, validation, and streaming |
| **Researcher** | Swap providers, models, and tools from config — run experiments without touching code |
| **MLOps engineer** | Validation scores, session replay, token accounting, and OpenTelemetry out of the box |

---

## What Cortex is *not*

- **Not a low-code builder.** It's a Python library — drive it with `cortex.yaml` *or* the `CortexBuilder` API. Either way, config replaces boilerplate, not your code.
- **Not an LLM gateway.** Bring your own API key.
- **Not a vector database.** It calls MCP tools that do RAG — it doesn't implement retrieval itself.
- **Not a web framework.** Cortex runs *inside* FastAPI/Django/Flask/Click.

---

## Documentation

| Document | Read this if you want to... |
|---|---|
| **[Overview](docs/OVERVIEW.md)** | ...understand what Cortex is, who it's for, and why it exists |
| **[Architecture](docs/ARCHITECTURE.md)** | ...see the internals: primary agent, task graph, MCP agents, validation |
| **[Features](docs/FEATURES.md)** | ...scan the full feature matrix |
| **[Getting Started](docs/GETTING_STARTED.md)** | ...build your first agent with working code |
| **[Use Cases](docs/USE_CASES.md)** | ...see real-world scenarios and reference architectures |
| **[Configuration](docs/CONFIGURATION.md)** | ...look up every `cortex.yaml` field |
| **[CLI Reference](docs/CLI.md)** | ...look up every `cortex` subcommand |
| **[Deployment](docs/DEPLOYMENT.md)** | ...ship to production |
| **[FAQ](docs/FAQ.md)** | ...find answers to common gotchas |
| **[Contributing](CONTRIBUTING.md)** | ...report bugs or submit PRs |

---

## Community & support

- **Issues**: file bugs and feature requests on [GitHub Issues](https://github.com/kritird/Cortex-Agent-Framework/issues)
- **Discussions**: ask questions on [GitHub Discussions](https://github.com/kritird/Cortex-Agent-Framework/discussions)
- **Security**: report vulnerabilities privately, not in public issues

---

## License

MIT — see [LICENSE](LICENSE). Use it commercially, fork it, ship it.

**Define once. Deploy anywhere. Let it learn.**
