Metadata-Version: 2.4
Name: agenarc
Version: 0.5.0
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"
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

Directed-graph Agent Orchestration Engine with protocol-execution-visualization decoupling.

## Core Philosophy

**"Mechanism and Strategy Separation"**

- **Kernel**: Ultra-stable, only responsible for secure scheduling and resource validation
- **Self-repair/Evolution**: Built by users within the graph flow
- **Asset Boundary**: `agrc://` virtual protocol isolation

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         AgenArc                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Protocol   │  │   Engine     │  │    Visualization    │   │
│  │    (DSL)    │  │  (Runtime)   │  │      (Future)      │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
│                                                                  │
│  JSON Schema       Execution Engine       React Canvas IDE        │
│  + Template        + Scheduler           (Coming Soon)           │
│  + Conditions      + StateManager                                │
│                     + CheckpointManager                          │
│                     + PluginManager                              │
└─────────────────────────────────────────────────────────────────┘
```

## Features

### Stage 1: MVP Engine (Complete)

- JSON Schema protocol definition
- ExecutionEngine core with linear flow
- Built-in operators: Trigger, Memory_I/O, Script_Node, Log, Context_Set, Context_Get
- CLI: `agenarc run <protocol.json>`

### Stage 2: Complete Execution Engine (Complete)

- **Router** - Conditional branching (if-else, switch-case)
- **Script_Node** - Custom scripts with AST safety
- **CheckpointManager** - File-based persistence for interruption recovery
- **AST Evaluator** - Safe expression evaluation

### Stage 3: Self-Evolution System (Complete)

- **.agrc Bundle format** - Self-contained agent package
- **VFS** - `agrc://` protocol mapping for secure file access
- **Asset_Reader** - Read files from bundle via VFS
- **Asset_Writer** - Write files with atomic operations
- **Runtime_Reload** - Hot reload scripts and plugins
- Schema + AST sanitizer dual validation chain

### Stage 4: Plugin System (Complete)

- **Hot_Plugin_Loader** - File watching + atomic reload + zero-downtime
- **Python/C++/External loaders** - Multi-language plugin support
- **Plugin development docs**

### Stage 5: Visualization Platform (Complete)

- **Web-based IDE** — Node graph editor with drag-and-drop
- **Real-time execution preview** — Watch nodes execute live
- **Context panel** — YAML tree view with collapsible nodes
- **Auto-save + undo/redo** — Lossless editing
- **Live status indicators** — Node execution states, API connectivity

## Quick Start

### Installation

```bash
pip install agenarc
```

### Run an Agent

```bash
# Run an .agrc agent bundle
PYTHONIOENCODING=utf-8 uv run agenarc run examples/my_first_agent.agrc --input '{"payload":"Hello"}'
# Or without uv:
# PYTHONIOENCODING=utf-8 python -m agenarc.cli run examples/my_first_agent.agrc --input '{"payload":"Hello"}'
```

## Examples

Located in `examples/` directory:

| 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) |

### Running Examples

```bash
# Multi-turn chat (requires LLM)
uv run agenarc run examples/my_first_agent.agrc --input '{"payload":"Hello!"}'
uv run agenarc shell examples/my_first_agent.agrc

# euchea — background service with Alt+A hotkey (PDF→code generation)
uv run agenarc serve examples/euchea.agrc
```

## CLI Commands

```bash
# Run an agent (.agrc) or protocol (.json)
uv run agenarc run my_agent.agrc
uv run agenarc run flow.json --input '{"key": "value"}' --mode async

# Interactive shell (REPL mode)
uv run agenarc shell my_agent.agrc

# Validate an agent or protocol
uv run agenarc validate my_agent.agrc
uv run agenarc validate flow.json

# Show agent/protocol info
uv run agenarc info my_agent.agrc
uv run agenarc info flow.json

# Service mode — event plugins (QQ bot, hotkey, etc.)
uv run agenarc serve my_agent.agrc

# Fallback (without uv):
# PYTHONIOENCODING=utf-8 python -m agenarc.cli run my_agent.agrc
```

## Node Types

| Type | Description |
|------|-------------|
| `Trigger` | Entry point for graph execution |
| `LLM_Task` | Execute LLM inference |
| `Router` | Conditional branching (multi-output: all matching conditions execute in parallel) |
| `Memory_I/O` | Read/write to persistent storage |
| `Script_Node` | Execute inline Python scripts |
| `Join` | Synchronize parallel branches (edge-based input collection) |
| `Log` | Log and pass through values |
| `Context_Set` | Set values in global context |
| `Context_Get` | Get values from global context |

## .agrc Bundle Structure

```
my_agent.agrc/
├── manifest.json      # Agent metadata
├── flow.json         # Workflow definition
├── prompts/          # Prompt templates
│   └── system.pt     # System prompt
├── scripts/          # Custom scripts (optional)
│   └── tool.py
├── plugins/           # Embedded Python plugins (optional, auto-discovered)
│   └── my_plugin/
│       ├── agenarc.json
│       └── plugin.py
└── assets/           # Static assets (optional)
```

### manifest.json

```json
{
  "name": "my_agent",
  "version": "1.0.0",
  "entry": "flow.json",
  "permissions": {
    "prompts": "r--",
    "scripts": "rw-",
    "assets": "r--"
  },
  "immutable_nodes": ["trigger_1"],
  "hot_reload": true
}
```

### flow.json

```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"
      }
    },
    {"id": "log_1", "type": "Log", "label": "Output"}
  ],
  "edges": [
    {"source": "trigger_1", "sourcePort": "payload", "target": "llm_1", "targetPort": "prompt"},
    {"source": "llm_1", "sourcePort": "response", "target": "log_1", "targetPort": "message"}
  ]
}
```

## Configuration

AgenArc uses YAML configuration for API keys and settings:

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

providers:
  openrouter:
    api_key: your-openrouter-api-key
    base_url: https://openrouter.ai/api/v1
    default_model: openrouter/free
    temperature: 0.7

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

agent:
  checkpoint_dir: ~/.agenarc

plugins:
  qq:
    ws_url: "ws://127.0.0.1:3001"
    token: "your-napcat-token"
```

**Supported API endpoints:**

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

Environment variables override config file:

- `AGENARC_OPENAI_API_KEY`
- `AGENARC_OPENAI_BASE_URL`
- `AGENARC_OPENAI_MODEL`
- `AGENARC_ANTHROPIC_API_KEY`
- `AGENARC_ANTHROPIC_MODEL`
- `AGENARC_CHECKPOINT_DIR`

## Development

### Project Structure

```
agenarc/
├── protocol/          # Protocol layer (JSON Schema)
├── engine/           # Execution layer
│   ├── executor.py   # Core engine
│   ├── state.py     # State management + CheckpointManager
│   └── evaluator.py # AST safe expression evaluator
├── operators/        # Built-in operators
│   ├── builtin.py   # Core operators (Trigger, Memory_I/O, Script_Node, Log, Context_Set, Context_Get)
│   ├── router.py    # Router operator
│   ├── join.py      # Join operator
│   ├── llm.py      # LLM operators
│   ├── evolution.py # Asset_Reader, Asset_Writer, Runtime_Reload
│   └── prompt_builder.py # Prompt_Builder
├── vfs/             # Virtual filesystem (agrc://)
├── plugins/         # Plugin system
├── graph/           # Graph data structures
└── cli/             # Command-line interface
```

### Running Tests

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=agenarc --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_builtin_operators.py -v
```

### Current Test Status

```
======================== 627 passed ========================
Coverage: ~79%
```

## Roadmap

| Phase | Features | Status |
|-------|----------|--------|
| v0.1 | MVP Engine | Complete |
| v0.2 | Complete Execution Engine | Complete |
| v0.3 | Self-Evolution System | Complete |
| v0.4 | Plugin System | Complete |
| v0.5 | Visualization Platform | Complete |

## License

MIT
