Metadata-Version: 2.4
Name: genagent-core
Version: 0.2.0
Summary: A generic autonomous AI agent framework with two-tier architecture, CodeAct, and modular prompt system.
Project-URL: Homepage, https://github.com/qiyaxiong/genagent-core
Project-URL: Repository, https://github.com/qiyaxiong/genagent-core
Project-URL: Bug Tracker, https://github.com/qiyaxiong/genagent-core/issues
Project-URL: Changelog, https://github.com/qiyaxiong/genagent-core/blob/master/CHANGELOG.md
Author: GenAgent Team
License: MIT
License-File: LICENSE
Keywords: agent,ai,autonomous,executor,genagent,llm,mcp,openai,planner
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: all
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: e2b-code-interpreter>=0.0.10; extra == 'all'
Requires-Dist: e2b>=0.14.0; extra == 'all'
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: hatch>=1.7.0; extra == 'dev'
Requires-Dist: pyflakes>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: vulture>=2.7; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: httpx>=0.24.0; extra == 'mcp'
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: memory
Requires-Dist: chromadb>=0.4.0; extra == 'memory'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'memory'
Provides-Extra: sandbox
Requires-Dist: e2b-code-interpreter>=0.0.10; extra == 'sandbox'
Requires-Dist: e2b>=0.14.0; extra == 'sandbox'
Description-Content-Type: text/markdown

# GenAgent Core

A generic autonomous AI agent framework with a two-tier architecture, CodeAct capabilities, and three-file planning mode.

## Installation

```bash
pip install genagent-core
```

With optional dependencies (Sandbox & Memory):
```bash
pip install genagent-core[all]
```

## Quick Start

```python
import asyncio
from genagent_core import GenAgent, AgentConfig

async def main():
    # 1. Configure the agent
    config = AgentConfig(
        llm={
            "default_provider": "openai",
            "providers": {
                "openai": {
                    "base_url": "https://api.openai.com/v1",
                    "api_keys": ["sk-..."]
                }
            }
        },
        sandbox={
            "enabled": True,
            "provider": "e2b",
            "api_key": "e2b_..."
        }
    )
    
    # 2. Initialize the framework
    agent = GenAgent(config)
    
    # 3. Run a task
    task_state = await agent.run(
        instruction="Analyze the top 3 AI agent frameworks and generate a comparison report."
    )
    
    print(f"Task completed. Status: {task_state.status}")

if __name__ == "__main__":
    asyncio.run(main())
```

## Core Features

1. **Two-Tier Architecture**: Planner Agent breaks down complex tasks into phases, while Executor Agents handle specific steps.
2. **Three-File Planning Mode**: Uses `task_plan.md`, `findings.md`, and `progress.md` for robust state management and seamless resume.
3. **CodeAct (Executable Python as Actions)**: Executors use a stateful Jupyter Kernel (`python_exec`) for data analysis, visualization, and multi-step logic. Variables persist across cells, and generated charts are automatically saved as artifacts.
4. **Seamless Resume**: If the process crashes, the Orchestrator reads the sandbox files to resume exactly where it left off.
5. **Smart Context Compression**: Two-phase deterministic context management (Compact → Summarize) to prevent context window overflow during long-running tasks.
6. **MCP Integration**: Connect any MCP-compatible server (stdio, SSE, or HTTP streaming) and its tools are automatically registered and available to all Executor agents.
7. **Skills System**: Teach Executor agents domain-specific workflows via Markdown `SKILL.md` files — injected into the system prompt at task start.

## Advanced Configuration

### MCP Servers

Connect any [Model Context Protocol](https://modelcontextprotocol.io/) server. Tools are automatically registered and available to all Executor agents.

Install the MCP dependency first:

```bash
pip install mcp httpx
```

```python
from genagent_core import AgentConfig
from genagent_core.config import MCPServerConfig

config = AgentConfig(
    mcp_servers={
        # stdio: spawn a local subprocess
        "filesystem": MCPServerConfig(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        ),
        # HTTP streaming: connect to a remote MCP server
        "my-api": MCPServerConfig(
            url="https://my-mcp-server.example.com/mcp",
            headers={"Authorization": "Bearer sk-..."},
            enabled_tools=["search", "fetch"],  # restrict to specific tools
            tool_timeout=60,
        ),
        # SSE: URL ending with /sse is auto-detected
        "sse-server": MCPServerConfig(
            url="https://my-mcp-server.example.com/sse",
        ),
    }
)

agent = GenAgent(config)
# MCP connections are established lazily on first agent.run() call
# and kept alive for the lifetime of the GenAgent instance.
# Call await agent.aclose() when done to cleanly shut down connections.
```

**Transport auto-detection** (when `type` is omitted):

| Condition | Transport |
|---|---|
| `command` is set | `stdio` |
| `url` ends with `/sse` | `sse` |
| `url` is set (other) | `streamableHttp` |

### Skills

Skills are Markdown files (`SKILL.md`) that teach Executor agents domain-specific workflows. They are injected into the system prompt at task start.

**Directory layout:**

```
skills/
  my-skill/
    SKILL.md        ← required
    scripts/        ← optional helper scripts
  another-skill/
    SKILL.md
```

**SKILL.md frontmatter:**

```markdown
---
name: my-skill
description: Brief description shown in the skills index.
always: false      # set true to always inject full content
metadata: {"requires": {"bins": ["git"], "env": ["MY_API_KEY"]}}
---
# My Skill
...
```

**Configuration:**

```python
from genagent_core import AgentConfig
from genagent_core.config import SkillsConfig

config = AgentConfig(
    skills=SkillsConfig(
        enabled=True,
        skills_dirs=["./skills"],        # directories to search for skills
        always_load=["coding-style"],    # always inject these skills in full
        inject_summary=True,             # inject <skills> XML index (default: True)
    )
)
```

**Two-tier injection strategy:**

| Tier | Trigger | Content injected |
|---|---|---|
| Full injection | `always: true` in frontmatter OR listed in `always_load` | Complete `SKILL.md` content |
| Index only | All other available skills | Compact `<skills>` XML summary |

The agent reads full skill content on demand via `file_read` when it needs the details. Skills with unmet requirements (`bins`/`env`) are listed as `available="false"` in the index.

### Context Compression

You can configure the context compression thresholds similar to LangChain's memory management:

```python
from genagent_core import AgentConfig
from genagent_core.config import ContextConfig

config = AgentConfig(
    context=ContextConfig(
        model_token_limit=128_000,
        compact_threshold=0.75,    # Phase 1: Truncate long tool results when context is 75% full
        summarize_threshold=0.90,  # Phase 2: Summarize old messages when context is 90% full
        max_tool_result_chars=3000 # Max characters to keep per tool result during Phase 1
    )
)
```

## License

MIT
