Metadata-Version: 2.4
Name: pycelest
Version: 0.8.0
Summary: A production-ready framework for building safe, capable, and observable AI agents with native connector integrations.
Project-URL: Homepage, https://github.com/eddycelestin15/celest
Project-URL: Documentation, https://github.com/eddycelestin15/celest#readme
Project-URL: Repository, https://github.com/eddycelestin15/celest
Project-URL: Issues, https://github.com/eddycelestin15/celest/issues
Author-email: Lovanirainy Theogene Eddy Celestin RAFANOMEZANA <eddy.celestin.raf@gmail.com>
License: Proprietary
License-File: LICENSE
Keywords: agents,ai,framework,llm,orchestration,react
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
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 :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: opentelemetry-api>=1.24
Requires-Dist: opentelemetry-sdk>=1.24
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: structlog>=24.0
Requires-Dist: tenacity>=8.0
Requires-Dist: tiktoken>=0.7
Requires-Dist: toml>=0.10
Provides-Extra: all
Requires-Dist: anthropic>=0.28; extra == 'all'
Requires-Dist: chromadb>=0.5; extra == 'all'
Requires-Dist: google-auth-httplib2>=0.2; extra == 'all'
Requires-Dist: google-auth>=2.0; extra == 'all'
Requires-Dist: langfuse>=2.0; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: openai>=1.30; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp>=1.24; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.45b0; extra == 'all'
Requires-Dist: python-telegram-bot>=21.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Requires-Dist: twilio>=9.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.28; extra == 'anthropic'
Provides-Extra: deepseek
Requires-Dist: openai>=1.30; extra == 'deepseek'
Provides-Extra: dev
Requires-Dist: httpx[cli]; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: types-toml; extra == 'dev'
Provides-Extra: gmail
Requires-Dist: google-auth-httplib2>=0.2; extra == 'gmail'
Requires-Dist: google-auth>=2.0; extra == 'gmail'
Provides-Extra: google
Requires-Dist: openai>=1.30; extra == 'google'
Provides-Extra: grok
Requires-Dist: openai>=1.30; extra == 'grok'
Provides-Extra: langfuse
Requires-Dist: langfuse>=2.0; extra == 'langfuse'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: meta
Provides-Extra: mistral
Requires-Dist: openai>=1.30; extra == 'mistral'
Provides-Extra: notion
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp>=1.24; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.45b0; extra == 'otel'
Provides-Extra: rag
Requires-Dist: chromadb>=0.5; extra == 'rag'
Requires-Dist: sentence-transformers>=3.0; extra == 'rag'
Provides-Extra: slack
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
Provides-Extra: whatsapp
Requires-Dist: twilio>=9.0; extra == 'whatsapp'
Description-Content-Type: text/markdown

# pycelest — AI Agent Framework

> **Build · Orchestrate · Defend · Connect · Sleep · Wake**
> The most innovative Python framework for production-grade AI agents.

[![PyPI version](https://badge.fury.io/py/pycelest.svg)](https://pypi.org/project/pycelest/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-566%20passed-brightgreen.svg)](#)
[![Coverage](https://img.shields.io/badge/coverage-84%25-green.svg)](#)

---

## What is pycelest?

pycelest is the **most innovative** Python framework for building AI agents — designed from day one for production deployment, not just demos.

It ships features that **no other framework has**: agents that sleep and wake up (Temporal Agents), agents that divide themselves into specialist sub-agents (Organic Topology), a behavioral immune system, DNA transfer between models, a distributed agent mesh, and an inter-agent negotiation protocol.

---

## Core Features

| Feature | Description |
|---|---|
| 🔁 **ReAct Loop** | Native Reasoning + Acting loop |
| 🌐 **Multi-Provider** | OpenAI · Anthropic · Google · Mistral · DeepSeek · Grok · Ollama · LM Studio · vLLM |
| 🧠 **Memory** | STM · Scratchpad · RAG · automatic compression |
| 🛡️ **Guardrails** | Tool Firewall · Execution Budget · ContentGuard (PII, injection) |
| 👥 **Multi-Agent** | AgentBus · Organic Topology (cell division) |
| 📡 **Streaming** | First-class async token streaming with SSE |
| 🔌 **Plugins** | Lifecycle hooks: `on_session_start`, `on_turn_end`, `on_tool_call`… |
| 🔗 **MCP Client** | `MCPAdapter` — consume any MCP server as agent tools |
| 🖥️ **MCP Server** | `MCPServer` — expose any agent as an MCP server (stdio / SSE) |
| 📬 **Native Connectors** | Gmail · Slack · Notion · Meta (connection pool, context manager) |
| 📊 **Observability** | Langfuse · OpenTelemetry · structlog |
| ⚙️ **Config** | Code or YAML — your choice |
| 💰 **Cost Optimization** | Prompt caching (Anthropic) · ModelRouter · FallbackAdapter |

---

## v1.0.0 Innovations (exclusive features)

| Innovation | API |
|---|---|
| ⏰ **Temporal Agents** — agents that sleep and auto-resume | `SuspendableSession`, `celest_suspend` tool |
| 🧬 **Organic Topology** — cell division, parallel sub-agents | `AgentNursery`, `spawn_subagent` tool |
| 🦠 **Agent Immune System** — behavioral anomaly detection | `ImmunePlugin`, `AgentQuarantined` |
| 🧪 **Agent DNA** — behavioral fingerprint transfer | `DNAExtractor`, `DNAInjector`, `AgentDNA` |
| 🕸️ **Celest Mesh** — distributed P2P agent network | `celest-mesh` package |
| 📜 **Celest Protocol** — agent-to-agent negotiation | `TaskBroker`, `CapabilityRegistry`, `verify_result` |
| ⚡ **Rate Limiter** — transparent adaptive rate limiting | `RateLimitedAdapter` |
| 🔄 **Session Replay** — replay past sessions with new provider | `SessionReplayer` |
| 🏦 **Memory Vault** — shared persistent knowledge base | `MemoryVault`, `MemoryVaultPlugin` |
| 🔍 **Prompt Optimizer** — analyze prompt compliance | `PromptOptimizer`, `PromptAnalysis` |
| 📊 **Agent Benchmarker** — evaluate agent quality | `AgentBenchmarker`, `BenchmarkReport` |
| 🛒 **Tool Marketplace** — discover and share tools | `ToolMarketplace`, `ToolPackage` |

---

## Installation

```bash
# Core framework
pip install pycelest

# With providers
pip install pycelest[anthropic]   # Claude
pip install pycelest[openai]      # GPT-4o, Gemini, DeepSeek, Mistral, Grok

# Extras
pip install pycelest[mcp]         # MCP client + server
pip install pycelest[langfuse]    # Observability
pip install pycelest[gmail]       # Gmail connector
pip install pycelest[rag]         # ChromaDB RAG

# Everything
pip install pycelest[all]
```

---

## Quick Start

```python
import asyncio
from celest import SessionManager, SessionConfig
from celest.providers import AnthropicAdapter

config = SessionConfig(
    system_prompt="You are a helpful, careful AI agent.",
    max_iterations=8,
)

session = SessionManager(
    config=config,
    provider=AnthropicAdapter(model="claude-sonnet-4-6", api_key="sk-ant-..."),
)

result = asyncio.run(session.run("Plan a 3-day trip to Kyoto"))
print(result.response)
```

---

## Temporal Agents — agents that sleep and wake up

The only framework where your agents can **suspend mid-execution** and automatically resume when a real-world condition is met.

```python
from celest.temporal import SuspendableSession, AgentSuspended

session = SuspendableSession(config=config, provider=provider)

try:
    result = await session.run(
        "Analyse the sprint results when PR #142 is merged, then notify Slack."
    )
except AgentSuspended as e:
    # Agent called celest_suspend(type="webhook", value="github.pr.merged")
    # Store e.snapshot.to_json() in DB, register e.snapshot.pause_condition.webhook_token
    pass

# When GitHub calls POST /temporal/webhook/{token}:
from celest.temporal import AgentStateSnapshot, SuspendableSession
snapshot = AgentStateSnapshot.from_json(stored_json)
resumed = SuspendableSession.from_snapshot(snapshot, provider=provider)
result = await resumed.resume(snapshot, resume_context="PR #142 merged at 14:32!")
```

**Supported conditions:** `time` (ISO datetime) · `webhook` (external event) · `human` (manual trigger) · `condition` (polled expression)

---

## Organic Topology — cell division for agents

Agents can **spawn specialized sub-agents** on-the-fly, run them in parallel, and synthesize merged results.

```python
# The agent uses built-in tools: spawn_subagent + await_subagents
result = await session.run("""
    Analyse these 50 GitHub PRs.
    Divide them into groups of 10, analyse each group in parallel
    using spawn_subagent, then synthesize with await_subagents.
""")
```

Access the nursery directly:
```python
child_id = await session._nursery.spawn("Analyse chapter 1", max_iterations=3)
results = await session._nursery.join_all()
```

---

## Agent Immune System — behavioral anomaly detection

Monitors running agents for suspicious patterns in real time.

```python
from celest.plugins.immune import ImmunePlugin, AgentQuarantined

session = SessionManager(
    config=config,
    provider=provider,
    plugins=[
        ImmunePlugin(
            auto_quarantine=True,       # stop on critical anomaly
            on_anomaly=my_alert_fn,     # webhook / SSE / log custom
        )
    ],
)

try:
    result = await session.run(user_prompt)
except AgentQuarantined as e:
    print(f"Agent quarantined: {e.event.rule_name} — {e.event.message}")
```

**Detects:** retry loops · cascade injection · token spikes · tool evasion · data hoarding

---

## Agent DNA — behavioral fingerprint transfer

Extract the "how" of a high-performing agent and inject it into a new one — even on a different model.

```python
from celest.dna import AgentDNA, DNAExtractor, DNAInjector

# Extract DNA from past sessions
dna = DNAExtractor().extract(past_results, past_histories, model_name="gpt-4o")
print(dna.summary())
# DNA{model=gpt-4o, sessions=12, depth=4.2(thorough), verbosity=0.35(concise), ...}

# Transfer to Claude
session = SessionManager(
    config=SessionConfig(system_prompt="You are a research analyst."),
    provider=AnthropicAdapter("claude-sonnet-4-6"),
    dna=dna,  # ← behavioral transfer
)

# Merge two DNA fingerprints (hybrid agent)
hybrid = dna_a.merge(dna_b, weight=0.4)  # 60% A + 40% B
```

---

## Celest Protocol — agent-to-agent negotiation

Universal protocol for agents to advertise capabilities, negotiate tasks, and return verifiable results.

```python
from celest.protocol import AgentRef, Capability, CapabilityRegistry, TaskBroker, verify_result

registry = CapabilityRegistry()
registry.advertise(AgentRef("agent:researcher"), [
    Capability("web_research", "Search the web", cost_per_call_usd=0.002)
])

broker = TaskBroker(agent=AgentRef("agent:orchestrator"), registry=registry)
result = await broker.delegate(
    description="Research AI trends 2026",
    input_data={"query": "AI trends"},
    executor=my_research_fn,
)

# Cryptographic verification
assert verify_result(result.payload["task_id"], result.payload["result"], result.payload["signature"])
```

---

## Rate Limiter — transparent rate limiting

```python
from celest.providers.rate_limiter import RateLimitedAdapter

session = SessionManager(
    config=config,
    provider=RateLimitedAdapter(
        provider=OpenAIAdapter("gpt-4o"),
        requests_per_minute=60,
        tokens_per_minute=100_000,
        retry_on_429=True,
    ),
)
# Transparent: queuing, backoff, and stats — no changes to your agent code
print(session.provider.stats)
```

---

## Memory Vault — shared knowledge base

```python
from celest.memory.vault import MemoryVault

vault = MemoryVault(".celest/vault.db", namespace="my-project")
vault.store("deploy_procedure", "Always run tests first, then docker build.", tags=["ops"])

# Auto-inject into agent sessions
session = SessionManager(
    config=config, provider=provider,
    plugins=[vault.as_plugin(inject_top_k=5)],
)
```

---

## Session Replay — A/B test providers

```python
from celest.replay import SessionReplayer

replayer = SessionReplayer()
result = await replayer.replay(
    history=original_history,
    new_provider=AnthropicAdapter("claude-sonnet-4-6"),
    original_provider_name="gpt-4o",
)
print(result.summary())
# Turn 1: similarity=0.82 [OK]
# Turn 2: similarity=0.31 [DIVERGE]
# Verdict: regression | Token delta: +142
```

---

## Prompt Optimizer

```python
from celest.optimizer import PromptOptimizer

analysis = PromptOptimizer().analyze(
    prompt=my_system_prompt,
    results=past_results,
    histories=past_histories,
)
print(analysis.report())
# ✅ "Reply in JSON"         — compliance: 91%
# ⚠️  "Always cite sources"  — compliance: 23%
# Suggestions: Strengthen instruction 1 with a concrete example.
```

---

## Agent Benchmarker

```python
from celest.benchmark import AgentBenchmarker

report = await AgentBenchmarker().run(
    session_factory=lambda: SessionManager(config=config, provider=provider),
)
print(report.summary())
# Score: 8.4/10 | Passed: 10/12 | Failed: 2/12
#   ✅ reasoning: 9.2   ✅ tool_use: 8.8   ⚠️  instruction_following: 6.1

# Detect regressions between versions
regression = new_report.compare(baseline_report)
print(regression.verdict)  # "improvement" | "neutral" | "regression"
```

---

## Tool Marketplace

```python
from celest.marketplace import ToolMarketplace, ToolPackage

market = ToolMarketplace()
market.publish([gmail_send, gmail_read], ToolPackage(
    name="celest-tools-gmail", tags=["email", "google"]
))

results = market.search("email")
tools = market.load("celest-tools-gmail")
session = SessionManager(config=config, provider=provider, tools=tools)
```

---

## Local Models (no API key)

```python
from celest.providers import OllamaAdapter

session = SessionManager(config=config, provider=OllamaAdapter(model="llama3.2"))
```

Install Ollama from [ollama.com](https://ollama.com), then `ollama pull llama3.2`.

---

## Native Connectors

```python
from celest.connectors.native.gmail import GmailConnector
from celest.connectors.native.slack import SlackConnector

async with GmailConnector(access_token="ya29....") as gmail:
    async with SlackConnector(bot_token="xoxb-...") as slack:
        session = SessionManager(
            config=config, provider=provider,
            tools=gmail.tools() + slack.tools(),
        )
```

---

## MCP Integration

```python
# Consume any MCP server as tools
from celest.tools.mcp import MCPAdapter

async with MCPAdapter(command="uvx", args=["mcp-server-time"]) as mcp:
    tools = await mcp.discover_tools()
    session = SessionManager(config=config, provider=provider, tools=tools)

# Expose your agent as an MCP server
from celest import MCPServer
server = MCPServer(session_factory=make_session, name="my-agent")
server.run_stdio()
```

---

## Changelog

| Version | Highlights |
|---|---|
| **v1.0.0** | Rate Limiter · Session Replay · Memory Vault · Prompt Optimizer · Agent Benchmarker · Tool Marketplace |
| **v0.9.0** | Celest Protocol (agent negotiation + verifiable results) |
| **v0.8.1** | Agent DNA (behavioral fingerprint + transfer) |
| **v0.8.0** | Agent Immune System (5 behavioral rules + auto-quarantine) |
| **v0.7.1** | Organic Topology (AgentNursery, spawn_subagent) |
| **v0.7.0** | Temporal Agents (SuspendableSession, pause/resume) |
| **v0.6.0** | Prompt caching · ModelRouter · ContentGuard · FallbackAdapter · Skills system |
| **v0.5.1** | Performance fixes · httpx pool · connector improvements |
| **v0.5.0** | `MCPServer` (stdio + SSE) · `MCPAdapter` auto-reconnect |
| **v0.4.0** | `LangfusePlugin` — full LLM observability |
| **v0.3.0** | Native connectors: Gmail · Slack · Notion · Meta |
| **v0.2.0** | Plugin system · AgentBus · Streaming · OpenTelemetry |
| **v0.1.2** | MCP client · RAG · Compression · YAML config |

---

## License

Proprietary © 2026 Lovanirainy Theogene Eddy Celestin RAFANOMEZANA — [flycelest.com](https://www.flycelest.com)
