pycelest 0.1.2

A production-ready framework for building safe, capable, and observable AI agents.

🌟 Pycelest — AI Agent Framework

Build · Orchestrate · Defend A production-ready framework for building safe, capable, and observable AI agents.

---

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 research.

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 at the core
🌐 Multi-Provider	OpenAI, Anthropic, Google, Mistral, DeepSeek, Grok — one interface
🏠 Local Models	Ollama, LM Studio, vLLM — no API key needed
🧠 Memory	STM, Scratchpad, RAG, and automatic compression
🛡️ Guardrails	Built-in Tool Firewall and Execution Budget
👥 Multi-Agent	Native agent collaboration via AgentBus
📡 Streaming	First-class async streaming from all providers
🔭 Observability	OpenTelemetry traces, metrics, and structured logs
🔌 Plugin System	Lifecycle hooks for extending behavior
⚙️ YAML Config	Code or YAML — your choice
🔧 MCP Support	Connect external tool servers via Model Context Protocol

---

Installation

pip install pycelest

# With specific provider
pip install pycelest[openai]      # OpenAI, Google, DeepSeek, Grok, Mistral
pip install pycelest[anthropic]   # Anthropic Claude

# Local models — no API key needed
# Install Ollama from https://ollama.com, then:
# ollama pull llama3.2

# Everything
pip install pycelest[all]

---

Quick Start

from celest import SessionManager, SessionConfig
from celest.providers import OpenAIAdapter

config = SessionConfig(
    system_prompt="You are a helpful, careful AI agent",
    max_iterations=8,
    max_tool_executions=10,
    token_budget=12_000,
)

session = SessionManager(
    config=config,
    provider=OpenAIAdapter(model="gpt-4o"),
)

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

---

Local Models (no API key)

from celest.providers import OllamaAdapter

session = SessionManager(
    config=config,
    provider=OllamaAdapter(model="llama3.2"),  # or mistral, phi3, qwen2.5...
)

---

With Tools

from celest.tools import FunctionTool

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

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

---

With YAML Config

# celest.yaml
system_prompt: "You are a helpful AI agent"
max_iterations: 8
provider: openai      # openai | anthropic | ollama | lmstudio | deepseek | grok | mistral
model: gpt-4o
guardrails:
  tool_firewall: ask  # accept | deny | ask

from celest import SessionManager

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

---

CLI

celest init                          # Generate a starter celest.yaml
celest run celest.yaml "Your prompt" # Run an agent from config

---

Multi-Agent

from celest.multi import AgentBus

bus = AgentBus()
researcher = SessionManager(config=research_config, provider=provider, bus=bus)
writer = SessionManager(config=write_config, provider=provider, bus=bus)

result = await researcher.run("Research and write a report on AI trends")

---

Architecture

User Input
    │
    ▼
[Optional: PlanningModule] ──► Goal decomposition + SkillRegistry
    │
    ▼
┌─────────────────────────────────────┐
│         SessionManager              │
│         (ReAct Loop)                │
│                                     │
│  ConversationHistory  MemoryManager │
│  ToolRegistry         RAGAdapter    │
│  PlanningModule       Logger        │
│  Compression          ExecBudget    │
└──────────────┬──────────────────────┘
               │
       ┌───────┴────────┐
       ▼                ▼
  ProviderAdapter   ToolFirewall
  (LLM API)         (Guardrails)

---

Roadmap

• Project scaffold & specification
• Phase 1 — Core: SessionManager, ReAct loop, ProviderAdapters, FunctionTool, Guardrails
• Phase 2 — Memory: STM, Scratchpad, RAG, Compression, Streaming, OpenTelemetry
• Phase 3 — Advanced: Plugin system, AgentBus, PlanningModule, MCP, CLI, Local models

---

Contributing

Contributions are welcome! Please open an issue or submit a PR on GitHub.

---

License

MIT © Celestin