genagent-core 0.2.0__tar.gz

genagent_core-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.env
+.genagent/
+.pytest_cache/

genagent_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-22
+
+### Added
+- **Modular Prompt System**: New `PromptLoader` class (`prompts/prompt_loader.py`) that assembles the system prompt from four independent Markdown files — `SOUL.md`, `AGENTS.md`, `TOOLS.md`, and `USER.md`. Prompts can now be overridden per-deployment without touching Python code.
+- **Prompt Files**: Added `AGENTS.md`, `SOUL.md`, `TOOLS.md`, and `USER.md` to `src/genagent_core/prompts/` as the canonical prompt source of truth.
+- **Enhanced `SkillLoader`**: Fully rewritten `skills/loader.py` with `SkillFrontmatter` dataclass, `strategy` field (`always` / `on_demand`), `requires` field for dependency checking, and `build_prompt_blocks()` for structured injection. Full backward compatibility with old `SkillsLoader` alias.
+- **`mcp` optional dependency group**: `pip install genagent-core[mcp]` now installs `mcp` and `httpx` for MCP server integration.
+- **`dev` optional dependency group**: `pip install genagent-core[dev]` installs all development and testing tools.
+- **PyPI classifiers and project URLs**: Package is now properly classified for PyPI discovery.
+- **GitHub Actions CI/CD**: Added `.github/workflows/ci.yml` (test on push) and `.github/workflows/publish.yml` (auto-publish to PyPI on version tag).
+
+### Changed
+- Bumped version to `0.2.0`.
+- `AgentFactory._build_fresh_context()` now uses `PromptLoader` to build the system prompt, replacing the previous hardcoded string concatenation.
+- `SkillLoader` now supports both new-style (`strategy: always`) and legacy-style (`metadata: {"always": true}`) frontmatter.
+- `_step_trim_cb` closure in `agent_factory.py` refactored to avoid function redefinition warning.
+
+### Fixed
+- Removed unused imports across 8 files (`agent.py`, `system_tools.py`, `mcp/client.py`, `orchestrator.py`, `event_bus.py`, `command_queue.py`, `search_service.py`, `agent_factory.py`).
+- Fixed `AgentConfig` undefined name in `orchestrator.py:from_config`.
+- Fixed missing `json` import in `event_bus.py`.
+- Fixed `ArtifactRef` unused import in `event_bus.py:rebuild_workspace_state`.
+
+## [0.1.0] - 2026-03-01
+
+### Added
+- Initial release of `genagent-core`.
+- Two-tier architecture: Planner Agent + Executor Sub-agents.
+- `GenAgent` high-level API with `async with` context manager support.
+- `AgentConfig` with `LLMConfig`, `ModelRoutingConfig`, `SandboxConfig`, `MemoryConfig`, `ContextConfig`, `SkillsConfig`, `MCPServerConfig`.
+- Built-in tools: filesystem (`fs_read`, `fs_write`, `fs_edit`, `fs_list`), system tools (`spawn_subagent`, `spawn_parallel`, `submit_plan`, `submit_results`), workflow tools (web search, browser automation).
+- MCP integration via `stdio`, `sse`, and `streamableHttp` transports.
+- Skills system with `SKILL.md` frontmatter and two-tier injection strategy.
+- Two-phase context compression (Compact → Summarize).
+- `EventBus` with typed `EventKind` enum and `subscribe` / `subscribe_all` API.
+- `CommandQueue` with per-workspace serialization and graceful drain on shutdown.

genagent_core-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GenAgent Team
+
+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.

genagent_core-0.2.0/PKG-INFO

@@ -0,0 +1,241 @@
+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

genagent_core-0.2.0/README.md

@@ -0,0 +1,189 @@
+# 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

genagent_core-0.2.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "genagent-core"
+version = "0.2.0"
+description = "A generic autonomous AI agent framework with two-tier architecture, CodeAct, and modular prompt system."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "GenAgent Team" }
+]
+keywords = [
+    "agent", "llm", "ai", "autonomous", "mcp",
+    "openai", "planner", "executor", "genagent",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "openai>=1.0.0",
+    "aiohttp>=3.8.0",
+    "jinja2>=3.1.0",
+    "tenacity>=8.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/qiyaxiong/genagent-core"
+Repository = "https://github.com/qiyaxiong/genagent-core"
+"Bug Tracker" = "https://github.com/qiyaxiong/genagent-core/issues"
+Changelog = "https://github.com/qiyaxiong/genagent-core/blob/master/CHANGELOG.md"
+
+[project.optional-dependencies]
+# E2B cloud sandbox for safe code execution
+sandbox = [
+    "e2b>=0.14.0",
+    "e2b-code-interpreter>=0.0.10",
+]
+# Vector memory backend (ChromaDB + sentence-transformers)
+memory = [
+    "chromadb>=0.4.0",
+    "sentence-transformers>=2.2.0",
+]
+# MCP (Model Context Protocol) tool server integration
+mcp = [
+    "mcp>=1.0.0",
+    "httpx>=0.24.0",
+]
+# Development and testing dependencies
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pyflakes>=3.0.0",
+    "vulture>=2.7",
+    "hatch>=1.7.0",
+]
+# Install everything
+all = [
+    "genagent-core[sandbox,memory,mcp]",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/genagent_core"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "README.md",
+    "CHANGELOG.md",
+    "pyproject.toml",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

genagent_core-0.2.0/src/genagent_core/__init__.py

@@ -0,0 +1,19 @@
+"""
+GenAgent Core: A generic autonomous AI agent framework.
+"""
+
+__version__ = "0.2.0"
+
+from .config import AgentConfig
+from .api_wrapper import GenAgent
+from .orchestration.orchestrator import Orchestrator
+from .agent.manus_agent import ManusAgent as PlannerAgent
+from .agent.manus_agent import ManusAgent as ExecutorAgent
+
+__all__ = [
+    "AgentConfig",
+    "GenAgent",
+    "Orchestrator",
+    "PlannerAgent",
+    "ExecutorAgent",
+]