Metadata-Version: 2.4
Name: logosai
Version: 0.11.0
Summary: Build AI agents in 4 lines. Orchestrate 55+ agents. Self-evolving.
Author-email: LogosAI Team <info@logosai.info>
Maintainer-email: LogosAI Team <info@logosai.info>
License: MIT License
        
        Copyright (c) 2023-2026 LogosAI
        
        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://github.com/maior/logosai-framework
Project-URL: Documentation, https://github.com/maior/logosai-framework#readme
Project-URL: Repository, https://github.com/maior/logosai-framework
Project-URL: Issues, https://github.com/maior/logosai-framework/issues
Keywords: ai,agent,llm,multi-agent,orchestration,framework,self-evolution,agentic
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: requests>=2.25.0
Requires-Dist: websocket-client>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Requires-Dist: anthropic>=0.3.0; extra == "llm"
Requires-Dist: google-genai>=1.0.0; extra == "llm"
Requires-Dist: langchain>=0.1.0; extra == "llm"
Requires-Dist: langchain-openai>=0.0.8; extra == "llm"
Requires-Dist: langchain-community>=0.0.28; extra == "llm"
Provides-Extra: all
Requires-Dist: logosai[llm]; extra == "all"
Requires-Dist: tavily-python>=0.3.0; extra == "all"
Requires-Dist: rich>=13.0.0; extra == "all"
Dynamic: license-file

# LogosAI

[![PyPI](https://img.shields.io/pypi/v/logosai.svg)](https://pypi.org/project/logosai/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Build AI agents in 4 lines. Orchestrate 55+ agents. Self-evolving.**

LogosAI is a Python framework for building, orchestrating, and evolving AI agents. Create a single agent with minimal code, or build a multi-agent system where agents collaborate, debate, learn from each other, and improve themselves autonomously.

```bash
pip install logosai
```

## Architecture

<p align="center">
  <img src="docs/architecture-overview.svg" alt="LogosAI System Architecture" width="100%"/>
</p>

<p align="center">
  <img src="docs/self-evolution-flow.svg" alt="Self-Evolution Flow" width="100%"/>
</p>

## Why LogosAI?

| | LogosAI | LangGraph | CrewAI | OpenAI SDK |
|---|---------|-----------|--------|------------|
| **Agent creation** | 4 lines | 30+ lines | 15+ lines | 10+ lines |
| **Built-in server** | `SimpleACPServer` | Manual | Manual | — |
| **Agent-to-agent** | `call_agent()` built-in | Manual wiring | Manual | — |
| **Agent debate** | 5-phase voting | — | — | — |
| **Self-evolution** | Auto-fix + auto-deploy | — | — | — |
| **L3 collaboration** | ask_opinion / share_finding | — | — | — |
| **L4 learning** | share_learning (persisted) | — | — | — |
| **Desktop control** | Gmail, KakaoTalk, Notion | — | — | — |
| **LLM providers** | OpenAI, Anthropic, Gemini, Ollama | OpenAI-centric | OpenAI-centric | OpenAI only |
| **Dynamic routing** | Tag-based auto-discovery | — | — | — |
| **Streaming** | SSE + WebSocket built-in | Custom | Custom | — |

## Quick Start

### 1. One-Line LLM Call

```python
import asyncio
from logosai import quick_llm

async def main():
    answer = await quick_llm("What is the capital of France?")
    print(answer)  # "The capital of France is Paris."

asyncio.run(main())
```

### 2. Build an Agent (4 Lines)

```python
from logosai import agent, AgentResponse

@agent(name="Joke Agent", description="Tells jokes about any topic")
async def joke_agent(query, context=None, llm=None):
    response = await llm.invoke(f"Tell a short joke about: {query}")
    return AgentResponse.success(content={"answer": response.content})
```

### 3. Build an Agent (Class-Based)

```python
from logosai import SimpleAgent, AgentResponse

class TranslatorAgent(SimpleAgent):
    agent_name = "Translator"
    agent_description = "Translates text between languages"

    async def handle(self, query, context=None):
        translation = await self.ask_llm(f"Translate to English: {query}")
        return AgentResponse.success(content={"answer": translation})
```

### 4. Run a Multi-Agent Server

```python
from logosai import SimpleAgent, AgentResponse
from logosai.acp import SimpleACPServer

class MathAgent(SimpleAgent):
    agent_name = "Math Agent"
    agent_description = "Solves math problems"

    async def handle(self, query, context=None):
        answer = await self.ask_llm(f"Calculate: {query}")
        return AgentResponse.success(content={"answer": answer})

server = SimpleACPServer(port=9000)
server.add(MathAgent())
server.run()
```

```bash
# List agents
curl localhost:9000/jsonrpc -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"list_agents"}'

# SSE streaming
curl -N "localhost:9000/stream?query=3+5&agent_id=math_agent"
```

### 5. LLM Client (Multi-Provider)

```python
from logosai import LLMClient

client = LLMClient(provider="google", model="gemini-2.5-flash-lite")
await client.initialize()

response = await client.invoke("Explain async/await in Python")
print(response.content)
```

Supported: `openai`, `anthropic`, `google` (Gemini), `ollama`

## Installation

```bash
pip install logosai          # Core framework
pip install logosai[llm]     # + LLM providers (OpenAI, Anthropic, Gemini)
pip install logosai[all]     # + All optional dependencies
```

## Features

### Core
- **`@agent` decorator** — 4-line agent creation
- **`SimpleAgent`** — Class-based with `ask_llm()` helper
- **`quick_llm()`** — One-shot LLM call
- **`LLMClient`** — Unified multi-provider client (OpenAI, Anthropic, Gemini, Ollama)
- **`LogosAIAgent`** — Full-featured base with async lifecycle

### Multi-Agent Orchestration
- **SimpleACPServer** — Host agents with JSON-RPC + SSE streaming
- **Message Bus** — Pub/sub with topic routing and priorities
- **Workflow Engine** — Sequential, parallel, hybrid execution
- **Dynamic Routing** — Tag-based auto-discovery, no hardcoded routes

### Agent Communication (4 Levels)

```
L1: call_agent()      — Data passing (query → result)
L2: Debate System     — 5-phase workflow negotiation (propose → vote → consensus)
L3: Collaboration     — ask_opinion(), share_finding(), request_help()
L4: Learning          — share_learning(), get_learnings() (persisted across sessions)
```

```python
# L1: Call another agent
result = await self.call_agent("internet_agent", "Seoul weather")

# L3: Ask for opinion (not just data — shares reasoning)
opinion = await self.ask_opinion("analysis_agent",
    "Is this a seasonal pattern?",
    my_analysis={"pattern": "March spike", "confidence": 0.6})

# L4: Share what you learned (persisted for all agents)
await self.share_learning(
    pattern="Gmail compose overlay breaks JS selectors",
    solution="Add &fs=1 to compose URL",
    tags=["gmail", "chrome"])

# L4: Learn from others
learnings = await self.get_learnings(tags=["gmail"])
```

### Self-Evolution

```python
from logosai.evolution import EvolutionSystem, EvolutionConfig

config = EvolutionConfig(enabled=True, llm_provider="google")
evolution = EvolutionSystem(agent, config)
await evolution.enable()
```

**Capabilities**: Self-Healing · Self-Growing · Self-Evaluation

**Safety**: Circuit Breaker (3 failures → 1h cooldown) · Confidence Gates · Fix History

### FORGE Agent Builder (Optional)

```bash
pip install logosai-forge
```

```python
from logosai_forge import ForgeClient

forge = ForgeClient()
result = await forge.create_agent("Calculate BMI from weight and height")
result = await forge.improve_agent(code, failure_log)      # Fix bugs
result = await forge.enhance_agent(code, "add caching")    # Add features
```

Autonomous evolution loop:
```
Agent fails → FailureLogger → 30% threshold → FORGE improves
→ Confidence Gate (≥0.95) → RollbackManager backup
→ hot_register (zero-downtime deploy) → EvolutionMonitor tracks
```

### Desktop Agent

Control your desktop through natural language — 55+ agents, each independent:

```
desktop_agent (dynamic LLM router — no hardcoded routes)
├── call_agent("kakaotalk_agent")       → KakaoTalk messaging
├── call_agent("mail_desktop_agent")    → Gmail read/compose/attach
├── call_agent("notion_desktop_agent")  → Notion pages/todos
├── call_agent("multi_ai_inquiry_agent") → ChatGPT/Claude/Gemini compare
├── call_agent("auto_report_agent")     → Scheduled search + delivery
└── screen_analyzer (lightweight 0.1s + Vision 3s fallback)
```

| Feature | macOS | Ubuntu |
|---------|-------|--------|
| Gmail read/compose/reply/attach | ✅ | ✅ Chrome CDP |
| KakaoTalk messaging | ✅ AppleScript | ❌ |
| Notion read/create/todos | ✅ Keyboard + Vision | ✅ |
| Multi-AI Inquiry | ✅ App + Chrome | ✅ Chrome |
| Auto Reports (scheduled) | ✅ | ✅ |
| ScreenAnalyzer (lightweight + Vision) | ✅ | ✅ |
| Intent Verification | ✅ | ✅ |

**ScreenAnalyzer**: Lightweight check first (~0.1s AppleScript/JS) → Vision fallback only when needed (~3s). **Intent Verification**: verifies all preconditions before irreversible actions.

### Auto Reports

```
"매일 아침 8시에 서울 날씨 검색해서 카카오톡으로 보내줘"
"비트코인이 8만달러 넘으면 메일로 알려줘"
```

Conditional execution · AI summary · Multi-channel (KakaoTalk/Gmail/Telegram)

Web management: `http://localhost:8010/auto-reports`

## Documentation

| Guide | Description |
|-------|-------------|
| [ACP Protocol](docs/ACP_PROTOCOL.md) | Agent Communication Protocol — endpoints, call_agent(), Auto Reports |
| [Building Agentic AI](docs/BUILDING_AGENTIC_AI.md) | LLM integration, collaboration, debate, evolution |
| [Building an ACP Server](docs/BUILDING_ACP_SERVER.md) | Deploy multi-agent servers with JSON-RPC + SSE |
| [Samples](samples/) | Runnable examples — ResearchAgent, calculator, hello world |

## Full Stack Quick Start

**macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/maior/logosai-framework/main/install-macos.sh | bash
```

**Ubuntu / Debian:**
```bash
curl -fsSL https://raw.githubusercontent.com/maior/logosai-framework/main/install-ubuntu.sh | bash
```

```bash
cd ~/logosai
./start.sh       # Start all services
./stop.sh        # Stop all services
./status.sh      # Check what's running
```

| Service | Port | Description |
|---------|------|-------------|
| logos_web | 8010 | Next.js frontend — chat UI, auto reports, [architecture](/architecture) |
| logos_api | 8090 | FastAPI backend — auth, streaming, memory, Telegram bot |
| ACP Server | 8888 | Agent runtime — 55+ agents, self-evolution, L3/L4 |
| PostgreSQL | 5432 | Database |

## Requirements

**Core**: Python 3.11+, aiohttp, pydantic, loguru

**LLM** (`pip install logosai[llm]`): openai, anthropic, google-genai, langchain

**Desktop Agent**: macOS: Peekaboo + Accessibility · Ubuntu: xdotool, xclip, scrot

**Full Stack**: Node.js 18+, PostgreSQL 14+

## Related Repositories

| Repository | Description |
|-----------|-------------|
| [logosai-ontology](https://github.com/maior/logosai-ontology) | Multi-agent orchestration (GNN+RL+KG+LLM) |
| [logosai-api](https://github.com/maior/logosai-api) | FastAPI backend server |
| [logosai-web](https://github.com/maior/logosai-web) | Next.js frontend |

## License

[MIT](LICENSE) — Copyright (c) 2023-2026 LogosAI

---

[PyPI](https://pypi.org/project/logosai/) · [GitHub](https://github.com/maior/logosai-framework) · [Issues](https://github.com/maior/logosai-framework/issues) · [Samples](samples/)
