Metadata-Version: 2.4
Name: alcyoneus
Version: 1.0.0
Summary: Alcyoneus OS: Production-grade Python operating system & framework for building, orchestrating, and deploying multi-agent LLM systems.
Author-email: Alcyoneus Authors <contact@alcyoneus.ai>
Maintainer-email: Ravinder Singh <contact@alcyoneus.ai>
License: MIT License
        
        Copyright (c) 2026 Ravinder Singh (Alcyoneus OS) & Contributors
        
        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://alcyoneus.alcyoneus.ai
Project-URL: Repository, https://github.com/alcyoneus-os/alcyoneus
Project-URL: Issues, https://github.com/alcyoneus-os/alcyoneus/issues
Project-URL: Documentation, https://alcyoneus.alcyoneus.ai
Keywords: agent,agents,ai-agent,ai-agents,multi-agent,multi-agent-systems,agentic,agentic-ai,agentic-workflow,agent-framework,agent-orchestration,orchestration,workflow,workflow-engine,state-machine,stategraph,graph,llm,llm-agent,llm-framework,llm-orchestration,llmops,genai,generative-ai,ai,artificial-intelligence,openai,anthropic,claude,gemini,google-genai,mcp,model-context-protocol,tool-use,function-calling,rag,memory,vector-store,qdrant,mem0,alcyoneus,alcyoneus-os,alcyoneus-sdk,sandboxing,voice-pipeline,guardrails,pydantic-ai,fastapi,react-agent,reasoning,chatbot,assistant,a2a
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: injectq>=0.4.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: google-genai
Requires-Dist: google-genai>=1.56.0; extra == "google-genai"
Provides-Extra: realtime
Requires-Dist: google-genai>=1.56.0; extra == "realtime"
Provides-Extra: openai
Requires-Dist: openai>=1.77.0; extra == "openai"
Provides-Extra: pg-checkpoint
Requires-Dist: asyncpg>=0.29.0; extra == "pg-checkpoint"
Requires-Dist: redis>=4.2; extra == "pg-checkpoint"
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.11.3; extra == "mcp"
Requires-Dist: mcp>=1.13.0; extra == "mcp"
Provides-Extra: images
Requires-Dist: Pillow>=10.0.0; extra == "images"
Provides-Extra: cloud-storage
Requires-Dist: cloud-storage-manager>=0.1.2; extra == "cloud-storage"
Provides-Extra: redis
Requires-Dist: redis>=4.2; extra == "redis"
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.8.0; extra == "kafka"
Provides-Extra: rabbitmq
Requires-Dist: aio-pika>=9.0.0; extra == "rabbitmq"
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.7.0; extra == "qdrant"
Provides-Extra: mem0
Requires-Dist: mem0ai>=0.1.117; extra == "mem0"
Provides-Extra: a2a-sdk
Requires-Dist: a2a-sdk>=0.2.7; extra == "a2a-sdk"
Requires-Dist: httpx>=0.27.0; extra == "a2a-sdk"
Requires-Dist: uvicorn>=0.30.0; extra == "a2a-sdk"
Requires-Dist: sse-starlette>=2.0; extra == "a2a-sdk"
Provides-Extra: browser
Requires-Dist: playwright>=1.50.0; extra == "browser"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Provides-Extra: cli
Requires-Dist: click>=8.1.0; extra == "cli"
Requires-Dist: rich>=13.0.0; extra == "cli"
Requires-Dist: pyyaml>=6.0; extra == "cli"
Provides-Extra: all-publishers
Requires-Dist: redis>=4.2; extra == "all-publishers"
Requires-Dist: aiokafka>=0.8.0; extra == "all-publishers"
Requires-Dist: aio-pika>=9.0.0; extra == "all-publishers"
Dynamic: license-file

<div align="center">
  <img src="assets/svg/alcyoneus-logo.svg" alt="Alcyoneus OS Banner" style="width: 100%; max-width: 100%; display: block; border-radius: 12px; margin-bottom: 16px;" />
  <p>
    <a href="https://github.com/sainibhaowal/Alcyoneus-OS/releases/tag/v1.0.0"><img src="https://img.shields.io/badge/Release-v1.0.0-00F0FF?style=flat-square&logo=github" alt="Release" /></a>&nbsp;
    <a href="https://github.com/sainibhaowal/Alcyoneus-OS"><img src="https://img.shields.io/badge/Python-3.12%20|%203.13-38BDF8?style=flat-square&logo=python" alt="Python Versions" /></a>&nbsp;
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3B82F6?style=flat-square" alt="License: MIT" /></a>&nbsp;
    <a href="https://github.com/sainibhaowal/Alcyoneus-OS/actions"><img src="https://img.shields.io/badge/CI-Passing-10B981?style=flat-square&logo=github-actions" alt="CI Status" /></a>&nbsp;
    <a href="https://github.com/sainibhaowal/Alcyoneus-OS"><img src="https://img.shields.io/badge/Coverage-80%25-10B981?style=flat-square" alt="Coverage" /></a>
  </p>
</div>

---

**Alcyoneus OS** is a production-grade Python framework for building intelligent agents and orchestrating multi-agent state-graph workflows. It provides an LLM-agnostic workflow engine with built-in persistence, streaming, human-in-the-loop, guardrails, multi-agent orchestration, sandboxing, and enterprise-grade observability.

```python
import alcyoneus as alc
from alcyoneus.core import StateGraph, Agent, ToolNode, START, END
from alcyoneus.storage.checkpointer import InMemoryCheckpointer
from alcyoneus.prebuilt.tools import safe_calculator, google_web_search

# 1. Define a tool
def get_weather(location: str) -> str:
    return f"It's sunny in {location}"

# 2. Build graph with Agent + tools
graph = StateGraph()
graph.add_node("agent", Agent(model="gemini/gemini-2.5-flash", tool_node="tools"))
graph.add_node("tools", ToolNode([get_weather]))
graph.add_edge("agent", "tools")
graph.add_edge("tools", "agent")
graph.set_entry_point("agent")

# 3. Run with persistence
compiled = graph.compile(checkpointer=InMemoryCheckpointer())
result = compiled.invoke(
    {"messages": [{"role": "user", "content": "Weather in NYC?"}]},
    config={"thread_id": "demo"}
)
```

---

## ✨ Key Features (100+ Production-Grade Capabilities)

### 🤖 Agent Engine & Orchestration
| Feature | Description |
|---------|-------------|
| **Agent Class** | Build complete agents in 10-30 lines |
| **StateGraph** | LangGraph-inspired engine with nodes, edges, conditional routing |
| **ReactAgent** | Reasoning + tool-use loops with ReAct pattern |
| **RAGAgent** | Retrieval-augmented generation with vector stores |
| **SwarmAgent** | Dynamic multi-agent collaboration |
| **SupervisorTeamAgent** | Hierarchical agent coordination |
| **PlanActReflectAgent** | Plan → Execute → Reflect cycles |
| **StructuredOutputAgent** | Guaranteed JSON schema output |
| **AudioAgent** | Real-time audio-to-audio (Gemini Live, OpenAI Realtime) |

### 🔄 Orchestration & Control Flow
| Feature | Description |
|---------|-------------|
| **StateGraph** | Nodes, edges, conditional routing, subgraphs |
| **Dynamic Routing** | `Command(goto=..., update=...)` for inline routing |
| **Subgraph Streaming** | Nested graph execution with `CompiledGraph` returns |
| **MessageGraph** | High-level message-only graph wrapper |
| **RemoteGraph/GraphServer** | HTTP/gRPC graph execution & serving |
| **Dynamic Inline Routing** | `Command(goto=..., update=...)` |
| **MessageGraph** | High-level message-only wrapper |
| **All/ALL Selector** | Catch-all edge routing (`*`, `All`, `ALL`) |

### 🤖 LLM Providers (100+ Models)
| Provider | Models |
|----------|--------|
| **OpenAI** | GPT-4o, GPT-4o-mini, o1, o3-mini, Responses API |
| **Google** | Gemini 2.5 Flash/Pro, Gemini Live, Vertex AI |
| **Anthropic** | Claude 3.5 Sonnet, Haiku, Opus |
| **LiteLLM** | 100+ models (Ollama, Together, Bedrock, etc.) |
| **MultiProvider** | Prefix routing: `openai/`, `gemini/`, `ollama/`, `anthropic/` |
| **Fallbacks** | Exponential backoff, multi-provider retry |

### 🛠️ 50+ Built-in Tools
| Category | Tools |
|----------|-------|
| **Search** | `google_web_search`, `bing_search`, `brave_search`, `duckduckgo_search`, `serpapi_search`, `tavily_search`, `exa_search`, `multi_search` (7 providers + dedup) |
| **Browser** | `browser_navigate`, `browser_click`, `browser_fill`, `browser_extract`, `browser_screenshot`, `browser_close` |
| **Shell** | `shell_command` (safe, policy-guarded) |
| **Code** | `code_interpreter`, `CodeInterpreterTool` (sandboxed Python) |
| **Files** | `file_read`, `file_write`, `list_directory`, `edit_file`, `file_search` (semantic + incremental) |
| **Search** | `google_web_search`, `vertex_ai_search` |
| **Image** | `generate_image`, `dalle_generate`, `imagen_generate`, `sdxl_generate`, `midjourney_generate` |
| **Code** | `code_interpreter`, `CodeInterpreterTool` |
| **Shell** | `shell_command` (policy-guarded), `ShellTool` |
| **Files** | `file_read`, `file_write`, `list_directory`, `edit_file` (unified diff), `file_search` |
| **Calendar** | `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`, `calendar_list_events` |
| **Scheduler** | `Scheduler`, `schedule_job`, `cancel_scheduled_job`, `list_scheduled_jobs` |
| **Subagents** | `start_subagent`, `SubagentManager`, `create_handoff_tool` |
| **Browser** | `browser_navigate`, `click`, `fill`, `extract`, `screenshot`, `close` |
| **Memory** | `memory_tool`, `create_memory_preload_node`, `make_agent_memory_tool` |
| **Image Gen** | `generate_image`, `dalle_generate`, `imagen_generate`, `sdxl_generate`, `midjourney_generate` |
| **Code** | `code_interpreter`, `CodeInterpreterTool` (sandboxed Python) |
| **Shell** | `shell_command` (policy-guarded), `ShellTool` (Docker/Local) |
| **Files** | `file_read`, `file_write`, `list_directory`, `edit_file` (unified diff), `file_search` |
| **Search** | 7 providers: Google, Bing, Brave, DuckDuckGo, SerpAPI, Tavily, Exa + `multi_search` |
| **Image Gen** | `generate_image` (unified), `dalle`, `imagen`, `sdxl`, `midjourney` |
| **Calendar** | `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`, `calendar_list_events` |
| **Scheduler** | `Scheduler`, `schedule_job`, `cancel_scheduled_job`, `list_scheduled_jobs` |
| **Subagents** | `start_subagent`, `SubagentManager`, `create_handoff_tool` |
| **Browser** | `browser_navigate`, `click`, `fill`, `extract`, `screenshot`, `close` |
| **Memory** | `memory_tool`, `create_memory_preload_node`, `make_agent_memory_tool` |

### 💾 Persistence & Memory (3-Layer Architecture)
| Layer | Implementation |
|-------|----------------|
| **Working State** | `AgentState` (Pydantic, in-memory) |
| **Checkpointer** | `InMemoryCheckpointer`, `PgCheckpointer` (PostgreSQL + Redis), `SqliteCheckpointer` |
| **Vector Store** | `QdrantStore`, `Mem0Store`, `MemoryConfig`, `AgentMemoryConfig` |
| **Memory Tools** | `memory_tool`, `create_memory_preload_node`, `make_agent_memory_tool` |
| **Compaction** | `DynamicCompactionPolicy`, `ResponsesCompactionSession` |
| **Session Storage** | SQLite, Redis, MongoDB, SQLAlchemy, Dapr, Encrypted |

### 🌊 Streaming & Real-time
| Feature | Description |
|---------|-------------|
| **Event Streaming** | `astream_events()` - 15 event types (graph/node/tool start/end, tool calls, handoffs, interrupts) |
| **GraphRunStream v3** | SSE streaming, heartbeat keep-alive, sync wrapper |
| **Granularity** | `LOW`/`PARTIAL`/`FULL` response granularity |
| **Realtime Audio** | `AudioAgent` (Gemini Live, OpenAI Realtime, Azure, Local Whisper+TTS) |
| **Barge-in** | Audio interruption with transcript persistence |
| **WebRTC Streaming** | `RemoteDesktopStreamer` for VNC/WebRTC frame broadcast |

### 🛡️ Security & Guardrails
| Feature | Description |
|---------|-------------|
| **Input Guardrails** | PII detection, prompt injection prevention, length limits |
| **Output Guardrails** | JSON schema enforcement, blocked words, length limits |
| **Tool Guardrails** | `ToolInputGuardrail`/`ToolOutputGuardrail` with allow/deny/rate limits |
| **Policy Engine** | 9-priority RBAC (allow/deny/ask_user), predicates, tenant scoping |
| **RBAC** | 9 permissions (Viewer/Dev/Admin/Owner), tenant scoping |
| **Auth** | JWT (JWKS), mTLS, Token Introspection (RFC 7662), API Key Manager |
| **Secrets** | Vault, AWS/GCP/Azure Key Vault, Composite fallback chain |

### 🌐 Protocols & Communication
| Protocol | Implementation |
|----------|----------------|
| **A2A** | Server (Starlette, agent cards, streaming), Client (retries, pooling, TLS) |
| **ACP** | Client/Server (HTTP/in-memory), agent discovery, task delegation |
| **MCP** | Stdio/SSE/WebSocket transports, capability negotiation, 5-min tool cache |
| **A2A Server** | Starlette app, agent cards, task streaming, uvicorn |
| **ACP** | HTTP/in-memory transports, agent discovery, task delegation |

### 🛠️ Developer Experience & CLI
| Tool | Purpose |
|------|---------|
| **`alc` CLI** | `alc graph create/run/visualize/validate`, `alc agent create`, `alc tool list/test`, `alc config`, `alc deploy docker/helm/k8s` |
| **Graph Visualizer** | `compiled.generate_graph("mermaid" \| "graphviz" \| "html")` - renders in GitHub, Notion, browser |
| **Graph Visualizer** | Interactive HTML with browser preview |
| **Graph Debug** | `alc debug state/replay/trace` for debugging checkpoints and traces |

### 🖥️ Sandboxing & Isolation
| Backend | Capabilities |
|---------|-------------|
| **DockerSandbox** | GPU passthrough, resource limits, volume mounts, PTY |
| **K8sSandbox** | Pod lifecycle, exec, resource quotas, GPU |
| **FirecrackerSandbox** | Micro-VM, resource isolation |
| **LocalSandbox** | Unix PTY, subprocess |
| **Computer Use** | X11/Wayland/Headless/VNC/Remote Desktop, Accessibility Bridge, Action Verifier |
| **ShellTool** | Docker/Local environments, policy-guarded, workspace scoping |

### 📊 Observability & Observability
| Feature | Description |
|---------|-------------|
| **OpenTelemetry** | Auto-instrumentation decorators (`@trace_graph`, `@trace_node`, `@trace_llm`, `@trace_tool`) |
| **Prometheus** | 15+ metrics (requests, latency, tokens, errors, sessions) |
| **Structured Logging** | JSON + W3C traceparent propagation |
| **8 Span Types** | Agent, Generation, Function, Guardrail, Handoff, Custom, Task |
| **Tracing** | Nested spans, processors (OTLP, Datadog, Console) |

### 🧪 Testing & Evaluation
| Tool | Purpose |
|------|---------|
| `QuickTest` | One-liner single/multi-turn assertions |
| `TestAgent` | Full simulation with `MockLLM`, `MockToolRegistry` |
| `MockMCPClient` | MCP server mocking |
| `AgentEvaluator` | LLM-as-judge, trajectory matching, safety, hallucination |
| `QuickTest` | One-liner single/multi-turn assertions |
| `TestContext` | Isolated test environments |
| `UserSimulator` | AI-powered user simulation (personas, error injection) |
| `BatchSimulator` | Concurrent simulation runs |

### 🏭 Production Hardening (17 Phases Complete)
| Phase | Area | Status |
|-------|------|--------|
| 1 | Sandbox Hardening | ✅ Docker, K8s, Firecracker, RemoteFileSync |
| 2 | Computer Use | ✅ X11/Wayland/Headless/VNC/Remote Desktop/Accessibility |
| 3 | Shell Tool | ✅ Docker/Local environments, policy-guarded |
| 4 | Web Search | ✅ 7 providers + multi_search dedup |
| 5 | Image Gen | ✅ DALL-E, Imagen, SDXL, Midjourney |
| 5b | File Search | ✅ Semantic index, incremental, multi-repo |
| 6 | Realtime Audio | ✅ OpenAI/Azure Realtime, Local Whisper+TTS |
| 7 | Distributed Sync | ✅ yjs/Automerge CRDT, mDNS/Consul |
| 8 | MCP Transports | ✅ Stdio/SSE/WebSocket, capability negotiation |
| 9 | A2A/ACP | ✅ Server/Client, streaming, agent cards |
| 10 | Observability | ✅ Auto-instrumentation, 15 Prometheus metrics |
| 11 | Multi-tenancy | ✅ TenantRegistry, quotas, RBAC, isolation |
| 12 | AuthZ/AuthN | ✅ JWT/mTLS/Token Introspection, ASGI middleware |
| 13 | Deployment | ✅ Docker, Helm, K8s Operator, systemd |
| 14 | Secrets | ✅ Vault/AWS/GCP/Azure + Composite fallback |
| 15 | Rate Limiting | ✅ Redis sliding-window, priority-weighted |
| 16 | Audit/Compliance | ✅ AuditLogger, GDPR, DataLineage, OPA, SBOM |
| 17 | Developer UX | ✅ `alc` CLI, Graph Visualizer (Mermaid/Graphviz/HTML) |

---

## Quick Install

```bash
# Core
pip install alcyoneus

# Common stacks
pip install "alcyoneus[openai,google-genai,mcp,pg_checkpoint,qdrant]"
pip install "alcyoneus[realtime]"      # Audio agents
pip install "alcyoneus[browser]"       # Browser automation
pip install "alcyoneus[cli]"           # CLI tools
```

```bash
export OPENAI_API_KEY=sk-...    # or GEMINI_API_KEY, ANTHROPIC_API_KEY
```

---

## 30-Second Example

```python
from alcyoneus.core import StateGraph, Agent, ToolNode, START, END
from alcyoneus.storage.checkpointer import InMemoryCheckpointer
from alcyoneus.prebuilt.tools import safe_calculator, google_web_search

graph = StateGraph()
graph.add_node("agent", Agent(model="gemini/gemini-2.5-flash", tool_node="tools"))
graph.add_node("tools", ToolNode([safe_calculator, google_web_search]))
graph.add_edge("agent", "tools")
graph.add_edge("tools", "agent")
graph.set_entry_point("agent")

compiled = graph.compile(checkpointer=InMemoryCheckpointer())
result = compiled.invoke(
    {"messages": [{"role": "user", "content": "What's 25 * 4?"}]},
    config={"thread_id": "demo"}
)
```

---

## Documentation

| Topic | Link |
|-------|------|
| **Quickstart** | [docs/QUICKSTART.md](docs/QUICKSTART.md) |
| **All Imports** | [docs/IMPORTS.md](docs/IMPORTS.md) |
| **Core Patterns** | [docs/CORE_PATTERNS.md](docs/CORE_PATTERNS.md) |
| **Prebuilt Agents** | [docs/PREBUILT_AGENTS.md](docs/PREBUILT_AGENTS.md) |
| **Tools** | [docs/TOOLS.md](docs/TOOLS.md) |
| **Persistence** | [docs/PERSISTENCE.md](docs/PERSISTENCE.md) |
| **Streaming** | [docs/STREAMING.md](docs/STREAMING.md) |
| **Testing** | [docs/TESTING.md](docs/TESTING.md) |
| **Evaluation** | [docs/EVALUATION.md](docs/EVALUATION.md) |
| **Skills** | [docs/SKILLS.md](docs/SKILLS.md) |
| **Security** | [docs/SECURITY.md](docs/SECURITY.md) |
| **Protocols** | [docs/PROTOCOLS.md](docs/PROTOCOLS.md) |
| **Configuration** | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) |
| **Deployment** | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) |
| **Project Structure** | [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) |
| **Common Issues** | [docs/GOTCHAS.md](docs/GOTCHAS.md) |

---

## Examples

```bash
# Basic agent
python examples/react/react_sync.py

# MCP integration
pip install "alcyoneus[mcp]"
python examples/react-mcp/server.py  # terminal 1
python examples/react-mcp/react-mcp.py  # terminal 2

# Streaming
python examples/react_stream/stream_react_agent.py

# Realtime audio
pip install "alcyoneus[realtime]"
export GEMINI_API_KEY=...
python examples/realtime/audio_agent_file.py
```

---

## Testing & Quality

```bash
# Run all tests (3159 passing)
pytest tests/ -q

# Lint
ruff check . && ruff format .

# Type check
mypy alcyoneus/
```

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

## Links

- **GitHub Repository**: https://github.com/sainibhaowal/Alcyoneus-OS
- **Documentation**: [docs/QUICKSTART.md](docs/QUICKSTART.md)
- **Examples**: [examples/](examples/)
- **License**: [LICENSE](LICENSE)

---

**Alcyoneus OS** — Build intelligent agents with confidence.
