Metadata-Version: 2.4
Name: pycelest
Version: 1.0.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**
> A production-ready Python framework for safe, capable, and observable 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/)
[![License](https://img.shields.io/badge/license-Proprietary-lightgrey.svg)](#license)

---

## What is pycelest?

pycelest is a Python framework for building AI agents that are **safe**, **capable**, and **observable** — designed from day one for production deployment, not just demos.

Unlike frameworks that bolt guardrails on as an afterthought, pycelest puts security, traceability, and reliability at the center of its architecture.

---

## Features

| Feature | Description |
|---|---|
| 🔁 ReAct Loop | Native Reasoning + Acting loop |
| 🌐 Multi-Provider | OpenAI · Anthropic · Google · Mistral · DeepSeek · Ollama · LM Studio |
| 🧠 Memory | STM · Scratchpad · RAG · automatic compression |
| 🛡️ Guardrails | Tool Firewall · Execution Budget · token limits |
| 👥 Multi-Agent | Native agent collaboration via AgentBus |
| 📡 Streaming | First-class async token streaming |
| 🔌 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 (Facebook + Instagram) |
| 📊 Langfuse | `LangfusePlugin` — full LLM observability out of the box |
| ⚙️ YAML Config | Code or YAML — your choice |

---

## 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)
```

---

## 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`.

---

## With Tools

```python
from celest.tools import FunctionTool

@FunctionTool.register(description="Search the web for current information")
async def web_search(query: str) -> str:
    ...

session = SessionManager(config=config, provider=provider, tools=[web_search])
result = await session.run("What are the latest AI news?")
```

---

## MCP Client — consume any MCP server

```python
from celest.tools.mcp import MCPAdapter

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

# SSE (remote server) with auth + auto-reconnect
async with MCPAdapter(
    url="https://my-mcp-server.com/sse",
    headers={"Authorization": "Bearer sk-..."},
    auto_reconnect=True,
) as mcp:
    tools = await mcp.discover_tools()
```

---

## MCP Server — expose your agent as an MCP server

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

def make_session():
    return SessionManager(
        config=SessionConfig(system_prompt="You are a helpful assistant."),
        provider=AnthropicAdapter(model="claude-sonnet-4-6", api_key="sk-ant-..."),
    )

server = MCPServer(session_factory=make_session, name="my-agent")
server.run_stdio()   # or server.run_sse(port=8080)
```

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-agent": {
      "command": "python",
      "args": ["my_agent.py"]
    }
  }
}
```

---

## Native Connectors

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

gmail = GmailConnector(access_token="ya29....")
tools = gmail.get_tools()   # gmail_send, gmail_read

slack = SlackConnector(bot_token="xoxb-...")
tools += slack.get_tools()  # slack_send, slack_read

session = SessionManager(config=config, provider=provider, tools=tools)
```

---

## Observability with Langfuse

```bash
pip install pycelest[langfuse]
```

```python
from celest.plugins.langfuse import LangfusePlugin

plugin = LangfusePlugin(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="https://cloud.langfuse.com",
    agent_name="my-agent",
)

session = SessionManager(config=config, provider=provider, plugins=[plugin])
# Every run is now traced in Langfuse: turns, tool calls, tokens, latency
```

---

## YAML Config

```yaml
# celest.yaml
system_prompt: "You are a helpful AI agent"
max_iterations: 8
provider: anthropic
model: claude-sonnet-4-6
guardrails:
  tool_firewall: ask   # accept | deny | ask
```

```python
session = SessionManager.from_yaml("celest.yaml")
result = await session.run("Your task here")
```

---

## CLI

```bash
celest init                           # Generate starter celest.yaml
celest run celest.yaml "Your prompt"  # Run agent from config
```

---

## Changelog

| Version | Highlights |
|---|---|
| **v0.5.0** | `MCPServer` (stdio + SSE) · `MCPAdapter` auto-reconnect + auth headers |
| **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)
