Metadata-Version: 2.4
Name: pykel
Version: 1.8.0
Summary: A production-grade agentic AI framework for Python: a unified multi-provider model gateway with built-in observability, cost governance, memory, retrieval (RAG), multi-agent orchestration, and deterministic testing.
Project-URL: Homepage, https://github.com/kprasad7/kel
Project-URL: GitHub, https://github.com/kprasad7/kel
Project-URL: Repository, https://github.com/kprasad7/kel
Project-URL: Documentation, https://github.com/kprasad7/kel/blob/develop/USAGE.md
Project-URL: Design & Architecture, https://github.com/kprasad7/kel/blob/develop/DESIGN.md
Project-URL: Changelog, https://github.com/kprasad7/kel/blob/develop/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/kprasad7/kel/issues
Author: kvenkatprasad
License: MIT License
        
        Copyright (c) 2026 kvenkatprasad
        
        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.
License-File: LICENSE
Keywords: agent-orchestration,agentic-os,agents,ai,ai-agents,anthropic,artificial-intelligence,cohere,gemini,llm,llm-framework,llm-orchestration,mistral,multi-agent,openai,python,rag,vector-database
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: chromadb>=0.5; extra == 'all'
Requires-Dist: cohere>=5.11; extra == 'all'
Requires-Dist: fal-client>=0.5; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: google-genai>=0.5; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: mistralai>=1.0; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'all'
Requires-Dist: pgvector>=0.3; extra == 'all'
Requires-Dist: pinecone>=5.0; extra == 'all'
Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
Requires-Dist: pypdf>=4.0; extra == 'all'
Requires-Dist: qdrant-client>=1.10; extra == 'all'
Requires-Dist: replicate>=0.34; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Requires-Dist: weaviate-client>=4.6; extra == 'all'
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: chroma
Requires-Dist: chromadb>=0.5; extra == 'chroma'
Provides-Extra: cohere
Requires-Dist: cohere>=5.11; extra == 'cohere'
Provides-Extra: dev
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: qdrant-client>=1.10; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: weaviate-client>=4.6; extra == 'dev'
Requires-Dist: websockets>=12.0; extra == 'dev'
Provides-Extra: fal
Requires-Dist: fal-client>=0.5; extra == 'fal'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Requires-Dist: uvicorn>=0.23; extra == 'fastapi'
Provides-Extra: gemini
Requires-Dist: google-genai>=0.5; extra == 'gemini'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: mistral
Requires-Dist: mistralai>=1.0; extra == 'mistral'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == 'pdf'
Provides-Extra: pgvector
Requires-Dist: pgvector>=0.3; extra == 'pgvector'
Requires-Dist: psycopg[binary]>=3.1; extra == 'pgvector'
Provides-Extra: pinecone
Requires-Dist: pinecone>=5.0; extra == 'pinecone'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.10; extra == 'qdrant'
Provides-Extra: replicate
Requires-Dist: replicate>=0.34; extra == 'replicate'
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == 's3'
Provides-Extra: weaviate
Requires-Dist: weaviate-client>=4.6; extra == 'weaviate'
Provides-Extra: websockets
Requires-Dist: websockets>=12.0; extra == 'websockets'
Description-Content-Type: text/markdown

# kel — The Open-Source Agentic AI Framework for Python

**kel** is a production-grade **agentic AI framework for Python**: a unified multi-provider model gateway with built-in observability, cost governance, memory, retrieval (RAG), multi-agent orchestration, self-healing, and deterministic testing — engineered to close the gaps that **LLM orchestration frameworks** commonly leave open: opaque execution, no native cost control, no reproducible testing, and context/loop failures.

If you're evaluating **AI agent frameworks**, **production-ready agent orchestration libraries**, or a **Python framework for building autonomous AI agents** with real observability and cost governance — this is built for exactly that.

<p align="center">
  <img alt="build" src="https://img.shields.io/github/actions/workflow/status/kprasad7/kel/ci.yml?branch=develop&label=build&style=for-the-badge&logo=github&color=2ea44f">
  <img alt="security" src="https://img.shields.io/github/actions/workflow/status/kprasad7/kel/security.yml?branch=develop&label=security%20scan&style=for-the-badge&logo=trivy&color=blueviolet">
  <img alt="pypi" src="https://img.shields.io/pypi/v/pykel.svg?style=for-the-badge&label=pypi&color=3775a9&logo=pypi&logoColor=white">
  <img alt="license" src="https://img.shields.io/badge/license-MIT-yellow.svg?style=for-the-badge">
  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=for-the-badge&logo=python&logoColor=white">
  <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-ff69b4.svg?style=for-the-badge">
</p>

<p align="center">
  <a href="https://github.com/kprasad7/kel"><strong>GitHub</strong></a> ·
  <a href="https://pypi.org/project/pykel/"><strong>PyPI</strong></a> ·
  <a href="https://github.com/kprasad7/kel/blob/develop/DESIGN.md"><strong>Design & Architecture</strong></a> ·
  <a href="https://github.com/kprasad7/kel/blob/develop/USAGE.md"><strong>Usage Guide</strong></a> ·
  <a href="https://github.com/kprasad7/kel/issues"><strong>Issues</strong></a>
</p>

> Install with `pip install pykel` — the PyPI distribution is named **pykel** (the `kel` name was already registered), but the import stays `import kel` and the CLI command stays `kel`.

---

## Why kel

| Common pain point in LLM orchestration frameworks | How kel solves it |
|---|---|
| No first-class tracing — bolt on a third-party observability product or go without | Every call traced by default, self-hostable via Grafana/OTel |
| Hidden token/cost consumption, surprise bills | Budget objects threaded through every call — hard caps, not suggestions |
| Deeply nested abstractions, painful debugging | Flat, composable classes — no multi-layer wrapper hierarchies to step through |
| Agents loop forever, no stuck-loop detection | Built-in stuck-loop + step-budget guardrails |
| No deterministic testing story | Record/replay testing — real API calls once, deterministic CI forever |
| Multi-agent state gets lost between agents | Shared context bus — downstream agents see what upstream agents *decided* |
| Real disclosed CVEs (deserialization, path traversal, SQLi) | Hardened by design — restricted unpickling, parameterized queries, Trivy-scanned every push |
| Forces credentials everywhere | Credentials optional by design — works natively on EC2/EKS/IAM roles, IRSA, self-hosted anonymous access |
| Single shared agent instance means every caller shares one conversation | Per-session `Agent` factories in the FastAPI/WebSocket adapters — one isolated conversation per session, no extra plumbing |

---

## Feature Highlights

- **Model Gateway** — one interface across **Anthropic, OpenAI, Cohere, Gemini, Mistral**, sync + real async
- **Observability** — every span traced automatically → console, Grafana, or the built-in live dashboard
- **Budget & Rate Limiting** — token/cost/tool-call caps + RPM/TPM throttling, composable
- **Caching** — in-memory or SQLite response caching, never double-charges budget on a hit
- **Memory** — working / episodic / semantic / procedural, layered like a real cognitive architecture
- **Retrieval (RAG)** — Qdrant, Pinecone, Weaviate, Chroma, pgvector, hybrid search, recursive splitting, PDF loading
- **Multi-Agent Orchestration** — sequential, supervisor, parallel, and swarm patterns, streaming included
- **Brain** — fast rule/embedding routing with LLM fallback, parallel-to-finish scheduling
- **Self-Healing** — diagnosis-driven retries with a non-negotiable idempotency guardrail
- **Built-in Tools** — web search (7 providers), URL fetch, Python/shell exec, SQL query, MCP servers
- **Media Generation** — image, video, text-to-speech, and lipsync via a generic gateway (fal.ai, Replicate), open for other vendors
- **Testing** — record/replay + LLM-graded evaluation, no live API key needed in CI
- **Live Monitoring Dashboard** — zero-dependency, real-time metrics + logs in your browser
- **Production Deploy Adapters** — stdlib HTTP, real WebSocket, and FastAPI (with per-session Agent isolation) — see USAGE.md §14
- **DevSecOps Built In** — Trivy vulnerability/secret scanning, `pip-audit`, and Bandit SAST on every push

---

## Install

```bash
pip install pykel               # from PyPI — import kel, run `kel`, same as always
pip install "pykel[anthropic]"  # + Anthropic
pip install "pykel[openai]"     # + OpenAI
pip install "pykel[gemini]"     # + Google Gemini
pip install "pykel[mistral]"    # + Mistral
pip install "pykel[qdrant]"     # + Qdrant vector store
pip install "pykel[fastapi]"    # + FastAPI production adapter
pip install "pykel[fal]"        # + fal.ai image/video/audio/lipsync generation
pip install "pykel[replicate]"  # + Replicate image/video/audio generation
pip install "pykel[all]"        # everything
```

Working from a clone instead: `pip install -e ".[dev]"` (or `-e ".[all]"`
for every extra).

## Quickstart

```python
from kel import get_model, Message

model = get_model("anthropic:claude-sonnet-5", api_key="...")
response = model.generate([Message.user("Hello!")])
print(response.text)
```

Swapping providers is a one-line change — same interface, zero rewrites:

```python
model = get_model("openai:gpt-5.2", api_key="...")
model = get_model("gemini:gemini-2.5-flash")      # falls back to env vars / ADC
model = get_model("mistral:mistral-large-latest")  # falls back to MISTRAL_API_KEY
```

A minimal tool-calling agent, deployed as a production FastAPI app with
one Agent per session (see USAGE.md §14 for the full walkthrough):

```python
from kel.agents import Agent
from kel.sdk import create_fastapi_app

def make_agent() -> Agent:
    return Agent("assistant", get_model("anthropic:claude-sonnet-5"))

app = create_fastapi_app(make_agent)   # pass a factory, not an instance
# uvicorn app:app — POST /invoke {"input": "...", "session_id": "user-42"}
```

---

## Status

Every subsystem in [DESIGN.md](https://github.com/kprasad7/kel/blob/develop/DESIGN.md) has a working, tested implementation — model gateway, observability, budget, context/loop, memory, retrieval, specs, runtime graph, multi-agent orchestration, brain, self-healing, testing, storage, SDK/CLI, monitoring dashboard, and realtime orchestration (interfaces only, by design — see DESIGN.md §7). Known gaps are listed honestly at the bottom of [USAGE.md](https://github.com/kprasad7/kel/blob/develop/USAGE.md) — no overclaiming.

## Security

Every push and pull request runs a full DevSecOps pipeline: [Trivy](https://github.com/aquasecurity/trivy) filesystem + secret scanning, `pip-audit` for known CVEs in dependencies, and Bandit static analysis over the codebase. Results surface in the repo's Security tab. See [`security.yml`](https://github.com/kprasad7/kel/blob/develop/.github/workflows/security.yml). To report a vulnerability, see [SECURITY.md](https://github.com/kprasad7/kel/blob/develop/SECURITY.md).

## Contributing

Issues and PRs welcome — see [CONTRIBUTING.md](https://github.com/kprasad7/kel/blob/develop/CONTRIBUTING.md). Adding a new model provider, vector store, or tool follows the same lazy-import adapter pattern throughout the codebase — see any file under `src/kel/models/providers/` for the template.

## License

[MIT](https://github.com/kprasad7/kel/blob/develop/LICENSE) © kvenkatprasad
