Metadata-Version: 2.4
Name: agenarc
Version: 0.7.1
Summary: Directed-graph Agent Orchestration Engine
Author: Rycbartbad
License: MIT
Project-URL: homepage, https://github.com/Rycbartbad/agenarc
Project-URL: repository, https://github.com/Rycbartbad/agenarc
Keywords: agent,orchestration,graph,workflow,llm,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: openai>=1.0
Provides-Extra: llm
Requires-Dist: anthropic>=0.30; extra == "llm"
Provides-Extra: plugins
Requires-Dist: watchdog>=4.0; extra == "plugins"
Requires-Dist: aiohttp>=3.9; extra == "plugins"
Requires-Dist: websockets>=12.0; extra == "plugins"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pyinstaller>=6.0; extra == "dev"
Provides-Extra: euchea
Requires-Dist: keyboard>=0.13; extra == "euchea"
Requires-Dist: markitdown>=0.1; extra == "euchea"
Requires-Dist: pdfplumber>=0.10; extra == "euchea"
Requires-Dist: PyMuPDF>=1.23; extra == "euchea"
Dynamic: license-file

# AgenArc

<div align="center">

**Directed-Graph Agent Orchestration Engine**

[![PyPI - Version](https://img.shields.io/pypi/v/agenarc?color=blue)](https://pypi.org/project/agenarc/)
[![Python](https://img.shields.io/pypi/pyversions/agenarc)](https://pypi.org/project/agenarc/)
[![License](https://img.shields.io/github/license/Rycbartbad/AgenArc)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-742%20passed-brightgreen)](https://github.com/Rycbartbad/AgenArc)
[![Coverage](https://img.shields.io/badge/coverage-62%25-yellow)](https://github.com/Rycbartbad/AgenArc)

</div>

---

## Philosophy

> **"Mechanism and Strategy Separation"**

| Layer | Role |
|-------|------|
| **Kernel** | Ultra-stable scheduler — secure execution, resource validation, VFS sandbox |
| **Self-repair** | Built by users within the graph flow — evolve agents without touching the engine |
| **Asset boundary** | `agrc://` virtual protocol — files, scripts, and prompts live in isolated bundles |

---

## Architecture

```
 ┌──────────────────────────────────────────────────────────┐
 │                      AgenArc v0.7                        │
 ├──────────────────────────────────────────────────────────┤
 │                                                           │
 │  ┌──────────┐    ┌──────────┐    ┌──────────────────┐    │
 │  │ Protocol │───▶│  Engine  │───▶│  Visualization   │    │
 │  │   (DSL)  │    │ (Runtime)│    │   (Web IDE)      │    │
 │  └──────────┘    └──────────┘    └──────────────────┘    │
 │        │               │                  │               │
 │  ┌─────▼─────┐  ┌──────▼──────┐  ┌───────▼────────┐     │
 │  │JSON Schema│  │  Scheduler  │  │  Graph Editor   │     │
 │  │+ Templates│  │  + Router   │  │  + Live Preview │     │
 │  │+ Conditions│ │  + Join     │  │  + Context Panel│     │
 │  └───────────┘  │  + Checkpoint│ │  + Status LEDs  │     │
 │                 │  + Plugins   │  └────────────────┘     │
 │                 └─────────────┘                          │
 └──────────────────────────────────────────────────────────┘
```

---

## Features

| Category | Highlights |
|----------|-----------|
| **Execution** | Linear & parallel & async modes, Router (conditional branching), Join (branch sync), CheckpointManager |
| **LLM** | Streaming responses, multi-provider fallback, structured error classification |
| **Scripting** | `Script_Node` with AST-safe evaluator (3 trust levels), gas & memory limits |
| **Packaging** | `.agrc` self-contained bundles — JSON protocol + prompts + scripts + plugins in one ZIP |
| **VFS** | `agrc://` virtual filesystem with `rwx` permissions, path-traversal protection |
| **Plugins** | Python / C++ / External loaders, hot-reload (file watching), event plugins |
| **Visualization** | Web IDE — graph editor, file tree editor, syntax highlighting, context panel, trace waterfall |
| **SubGraph** | Embed `.agrc` bundles as nodes — isolated context, auto port resolution, pack embedding |
| **CLI** | `run` / `shell` / `serve` / `validate` / `info` / `pack` / `visualize` / `init` |

## Node Types

| Node | Description | Input → Output |
|------|-------------|---------------|
| SubGraph | Embed and execute a nested `.agrc` bundle as a sub-graph with isolated context | auto-resolved from child bundle: trigger outputs → inputs, terminal node outputs → outputs |
| `Trigger` | Entry point | `payload` → graph |
| `Trigger` | Entry point | `payload` → graph |
| `LLM_Task` | LLM inference (streaming + fallback) | `messages` → `response`, `usage`, `error` |
| `Router` | Conditional branching (all matches execute in parallel) | `input` → dynamic output ports |
| `Join` | Synchronize parallel branches (merge / concat / first) | dynamic → `output` |
| `Memory_I/O` | Persistent key-value storage (transactional + checkpoint) | `key`, `value` → `value`, `success` |
| `Script_Node` | Inline Python with AST safety (3 trust levels) | arbitrary → `result` |
| `Prompt_Builder` | Multi-turn conversation history management | `user` / `assistant` → `messages` |
| `Log` | Log and pass-through | `message` → `message` |
| `Context_Set` | Set global context values | `key`, `value` → `success` |
| `Context_Get` | Read global context values | `key` → `value` |
| `Asset_Reader` | Read files from bundle via VFS | `path` → `content`, `success` |
| `Asset_Writer` | Write files with atomic operations | `path`, `content` → `success` |
| `Runtime_Reload` | Hot reload scripts and plugins at runtime | `target` → `success` |

---

## Quick Start

```bash
pip install agenarc
```

```bash
# Run a chat agent
agenarc run examples/my_first_agent.agrc --input '{"payload":"Hello!"}'

# Interactive REPL
agenarc shell examples/my_first_agent.agrc

# Background service with plugins
agenarc serve examples/euchea.agrc

# Web-based graph editor
agenarc visualize examples/my_first_agent.agrc
```

### Examples

| Agent | Description |
|-------|-------------|
| `my_first_agent.agrc` | Multi-turn chat — Trigger → Prompt_Builder → LLM_Task |
| `qq_bot_agent.agrc` | QQ bot with event plugin (`serve` mode) |
| `euchea.agrc` | PDF → C++ code generation via Alt+A hotkey (`serve` mode) |

---

## .agrc Bundle

```
my_agent.agrc/
├── manifest.json          # Metadata, permissions, hot_reload
├── flow.json              # Graph definition (nodes + edges)
├── prompts/
│   └── system.pt          # {{template}} prompt files
├── scripts/
│   └── tool.py            # Custom scripts (optional)
├── sub/                    # Embedded SubGraph bundles (auto-packed)
│   └── translator.agrc/
│       ├── flow.json
│       └── prompts/
├── plugins/                # Embedded plugins (auto-discovered)
│   └── my_plugin/
│       ├── agenarc.json
│       └── plugin.py
└── assets/                 # Static assets (optional)
```

<details>
<summary><b>Example flow.json</b></summary>

```json
{
  "version": "1.0.0",
  "nodes": [
    { "id": "trigger_1", "type": "Trigger", "label": "Start" },
    {
      "id": "llm_1",
      "type": "LLM_Task",
      "label": "Chat",
      "config": {
        "model": "deepseek-chat",
        "system_prompt": "agrc://prompts/system.pt",
        "stream": true,
        "providers": ["deepseek", "openrouter"]
      }
    },
    { "id": "log_1", "type": "Log", "label": "Output" }
  ],
  "edges": [
    { "source": "trigger_1", "sourcePort": "payload", "target": "llm_1", "targetPort": "messages" },
    { "source": "llm_1", "sourcePort": "response", "target": "log_1", "targetPort": "message" }
  ]
}
```

</details>

---

## SubGraph

An `.agrc` bundle can be embedded as a node in another graph:

```json
{
  "id": "translator",
  "type": "SubGraph",
  "label": "翻译 Agent",
  "config": { "bundle": "translator.agrc" }
}
```

SubGraph 端口自动从子图 bundle 解析：
- **输入端口** = 子图 Trigger 节点的输出端口
- **输出端口** = 子图终端节点（无出边）的输出端口

### Bundle 嵌入

引用 `sub/` 目录下的子图会在 `agenarc pack` 时自动嵌入：

```
my_agent.agrc/
├── flow.json              # 引用 sub/translator.agrc
├── sub/
│   └── translator.agrc/   # 运行时打包时自动嵌入
│       ├── flow.json
│       └── prompts/
```

### 上下文隔离

子图拥有独立的 `StateManager`，不污染父图上下文。父图可以通过 config.inputs 注入值，通过边连接子图的输出端口获取结果。

---

## Configuration

```yaml
# ~/.agenarc/config.yaml

providers:
  deepseek:
    api_key: sk-your-key
    base_url: https://api.deepseek.com
    default_model: deepseek-chat
    temperature: 0.7

  openrouter:
    api_key: sk-your-key
    base_url: https://openrouter.ai/api/v1
    default_model: openrouter/free

agent:
  checkpoint_dir: ~/.agenarc
```

| Provider | base_url |
|----------|----------|
| DeepSeek | `https://api.deepseek.com` |
| OpenAI | `https://api.openai.com/v1` |
| OpenRouter | `https://openrouter.ai/api/v1` |
| Ollama | `http://localhost:11434/v1` |

Environment variables override config: `AGENARC_OPENAI_API_KEY`, `AGENARC_OPENAI_BASE_URL`, `AGENARC_OPENAI_MODEL`, `AGENARC_ANTHROPIC_API_KEY`, `AGENARC_ANTHROPIC_MODEL`, `AGENARC_CHECKPOINT_DIR`

---

## Development

```
agenarc/
├── protocol/           # JSON Schema + protocol loader
├── engine/             # Executor, state manager, AST evaluator
├── operators/          # 13 built-in operators
├── vfs/                # agrc:// virtual filesystem
├── plugins/            # Plugin loader (Python/C++/External)
├── graph/              # Graph data structures + traversal
├── visualization/      # Web IDE server + static frontend
└── cli/                # Command-line interface
```

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/                          # All (742 passed)
pytest tests/ --cov=agenarc            # With coverage (~62%)
pytest tests/unit/test_builtin_operators.py -v  # Single file

# Lint & type check
ruff check agenarc/
ruff format --check agenarc/
mypy agenarc/
```

---

## Documentation

| Document | Description |
|----------|-------------|
| [CHANGELOG.md](CHANGELOG.md) | Release history and change log |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, PR process, commit style |
| [docs/agents.md](docs/agents.md) | User-facing agent creation guide (Chinese) |
| [docs/plugins/README.md](docs/plugins/README.md) | Plugin development guide |

---

## License

MIT © [Rycbartbad](https://github.com/Rycbartbad)
