Metadata-Version: 2.4
Name: vyane
Version: 0.30.0
Summary: Vyane — unified MCP server for cross-platform multi-model AI collaboration
Project-URL: Homepage, https://github.com/pure-maple/vyane
Project-URL: Repository, https://github.com/pure-maple/vyane
Project-URL: Issues, https://github.com/pure-maple/vyane/issues
Project-URL: Documentation, https://github.com/pure-maple/vyane#readme
Author: pure-maple
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,cli,codex,collaboration,gemini,mcp,multi-model,multiplexer,vyane
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.10
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
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.20.0
Requires-Dist: pydantic>=2.0
Provides-Extra: a2a
Requires-Dist: sse-starlette>=2.0.0; extra == 'a2a'
Provides-Extra: tui
Requires-Dist: textual>=1.0.0; extra == 'tui'
Description-Content-Type: text/markdown

# Vyane · 偃

English | [中文](docs/README_CN.md)

## Origin · 偃

> *"Can human craft rival the work of Nature herself?"* — King Mu of Zhou, on witnessing Yan Shi's automaton

*Vyane* (偃) is named after **Yan Shi** (偃师), the legendary artisan who crafted the first recorded automaton circa 1000 BCE. Just as Yan Shi orchestrated mechanical parts into a living whole, Vyane orchestrates multiple AI models into a unified, intelligent system.

[Read the full brand story →](docs/brand-story.md)

Cross-platform multi-model AI collaboration server. Dispatch, broadcast, and orchestrate tasks across **Codex CLI**, **Gemini CLI**, **Claude Code CLI**, **Ollama**, **DashScope** (Qwen/Kimi/MiniMax), and external **A2A agents** through a unified MCP + CLI interface — with smart routing v4, exponential retry, cost tracking, and multi-agent collaboration.

[![PyPI](https://img.shields.io/pypi/v/vyane)](https://pypi.org/project/vyane/)

## Why

Different AI models have different strengths:

| Model | Strengths |
|-------|-----------|
| **Codex** (GPT) | Code generation, algorithms, debugging |
| **Gemini** | Frontend/UI, multimodal, broad knowledge |
| **Claude** | Architecture, reasoning, code review |
| **Ollama** | Free local inference (DeepSeek, Llama, Qwen, etc.) |
| **DashScope** | Chinese models (Qwen, Kimi, MiniMax, GLM) |

Vyane lets any MCP-compatible platform orchestrate tasks across all of them — getting the best of each, with automatic failover, cost tracking, and true multi-agent collaboration.

## Architecture

```
MCP Client (Claude Code / Codex CLI / Gemini CLI / IDE)
    │
    └── Vyane (MCP server, stdio)
        ├── mux_dispatch     → single provider (auto-route, failover, retry)
        ├── mux_broadcast    → parallel multi-provider + comparison
        ├── mux_collaborate  → iterative multi-agent collaboration (A2A)
        ├── mux_workflow     → multi-step pipeline chains
        ├── mux_feedback     → user quality ratings (drives routing)
        ├── mux_history      → analytics, cost tracking
        └── mux_check        → availability & config status
            │
            ├── CodexAdapter      → codex exec --json
            ├── GeminiAdapter     → gemini -p -o stream-json
            ├── ClaudeAdapter     → claude -p
            ├── OllamaAdapter     → ollama run <model>
            ├── DashScopeAdapter  → OpenAI-compatible API
            ├── A2ARemoteAdapter  → external A2A agents (httpx)
            └── Custom Adapters   → user-defined plugins

CLI (`vyane` dispatch / broadcast)
    └── Same adapters + smart routing, JSON output for scripts & CI

A2A HTTP Server (`vyane` a2a-server)
    ├── GET  /.well-known/agent.json   → Agent Card
    ├── POST / (JSON-RPC 2.0)
    │   ├── tasks/send                 → synchronous task
    │   ├── tasks/get                  → query task state
    │   ├── tasks/cancel               → cancel running task
    │   └── tasks/sendSubscribe        → SSE streaming
    └── TaskStore (in-memory + JSONL persistence)
```

## Quick Start

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager
- At least one model CLI installed:
  - `codex` — `npm i -g @openai/codex`
  - `gemini` — `npm i -g @google/gemini-cli`
  - `claude` — [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
  - `ollama` — [Ollama](https://ollama.com)

### Install

```bash
# Recommended: install as MCP server for Claude Code
claude mcp add vyane -s user -- uvx vyane

# Or install for all platforms
git clone https://github.com/pure-maple/vyane.git
cd vyane && ./install.sh --all

# Quick availability check
vyane check
```

<details>
<summary>Manual installation for other platforms</summary>

```bash
# Codex CLI (~/.codex/config.toml)
[mcp_servers.vyane]
command = "uvx"
args = ["vyane"]

# Gemini CLI (~/.gemini/settings.json)
{"mcpServers": {"vyane": {"command": "uvx", "args": ["vyane"]}}}
```

</details>

## Usage

### Dispatch — single provider

```python
# Smart routing (auto-excludes caller, picks best model for the task)
mux_dispatch(provider="auto", task="Implement a binary search tree")

# Explicit provider
mux_dispatch(provider="codex", task="Fix the memory leak in pool.py",
             workdir="/path/to/project", sandbox="write")

# Specific model + multi-turn session
r1 = mux_dispatch(provider="codex", model="gpt-5.4", task="Analyze this codebase")
r2 = mux_dispatch(provider="codex", task="Fix the bug you found",
                   session_id=r1.session_id)

# Local model via Ollama
mux_dispatch(provider="ollama", model="deepseek-r1", task="Explain this algorithm")
```

### Broadcast — parallel multi-provider

```python
# Send to all available providers simultaneously
mux_broadcast(task="Review this API design for security issues")

# Specific providers with structured comparison
mux_broadcast(
    task="Suggest the best data structure for this use case",
    providers=["codex", "gemini", "claude"],
    compare=True  # adds similarity scores, speed ranking
)
```

### Collaborate — multi-agent iteration (A2A)

```python
# Review loop: implement → review → revise until approved
mux_collaborate(
    task="Implement a rate limiter with sliding window",
    pattern="review"  # codex builds, claude reviews, iterate
)

# Consensus: parallel analysis + synthesis
mux_collaborate(task="Evaluate our migration strategy", pattern="consensus")

# Debate: advocate vs critic + arbiter verdict
mux_collaborate(task="Should we use microservices?", pattern="debate")
```

### Workflow — multi-step pipelines

```python
# List available workflows
mux_workflow(workflow="", task="", list_workflows=True)

# Run a built-in or custom workflow
mux_workflow(workflow="review", task="Optimize the database queries")
```

### History & Cost Tracking

```python
# Recent dispatches
mux_history(limit=20)

# Statistics with cost breakdown
mux_history(stats_only=True, costs=True)

# Filter by provider and time range
mux_history(provider="codex", hours=24, costs=True)
```

Token usage is automatically extracted from Codex and Gemini responses. Cost estimation uses configurable per-model pricing.

### Check — availability & config

```python
mux_check()
# Returns: provider availability, caller detection, active profile,
#          policy summary, audit stats, active dispatches
```

## A2A HTTP Server

Expose Vyane as an [A2A protocol](https://google.github.io/A2A/) agent over HTTP:

```bash
# Start with default settings
vyane a2a-server

# Custom port + authentication
vyane a2a-server --port 8080 --token my-secret --sandbox write
```

Other A2A-compatible agents can discover and interact with Vyane via:
- `GET /.well-known/agent.json` — Agent Card (capabilities, skills)
- `POST /` — JSON-RPC 2.0 (`tasks/send`, `tasks/get`, `tasks/cancel`, `tasks/sendSubscribe`)

### Connecting to External A2A Agents

Register external agents in your config to use them as providers:

```toml
# ~/.config/vyane/profiles.toml
[a2a_agents.my-agent]
url = "http://localhost:8080"
token = "secret"
pattern = "code-review"
```

Then dispatch to them like any other provider:

```python
mux_dispatch(provider="my-agent", task="Review this PR")
```

## CLI Commands

```bash
# Server modes
vyane              # Start MCP server (stdio)
vyane a2a-server   # Start A2A HTTP server
vyane dashboard    # Web monitoring dashboard (http://127.0.0.1:41521)

# Direct task execution (JSON output, for scripts & CI)
vyane dispatch "Review this code"                       # auto-route
vyane dispatch -p codex -m gpt-5.4 "Fix the bug"       # explicit provider
vyane dispatch -p gemini --max-retries 3 "Analyze"      # with retry
vyane dispatch --failover "Fix this bug"                # auto-failover
cat diff.txt | vyane dispatch -p auto                   # pipe from stdin
vyane broadcast "Review this API" --providers codex gemini  # parallel
vyane broadcast --compare "Best data structure?"        # with analysis

# Feedback & management
vyane feedback --run-id abc --provider codex --rating 5 # rate results
vyane feedback --list                                   # view ratings
vyane check        # Check CLI availability
vyane check --json # JSON output for CI
vyane status -w    # Live dispatch monitor
vyane history --stats --costs   # Statistics with cost breakdown
vyane history --source cli-dispatch                     # filter by source
vyane benchmark    # Run provider benchmark suite
vyane export --format csv       # Export to CSV/JSON/Markdown

# Setup
vyane init         # Interactive configuration wizard
vyane config       # TUI configuration panel (requires vyane[tui])
vyane version      # Show version
```


## Configuration

Create `~/.config/vyane/profiles.toml` (user) or `.vyane/profiles.toml` (project):

```toml
# Custom routing rules
[routing]
default_provider = "codex"

[[routing.rules]]
provider = "gemini"
[routing.rules.match]
keywords = ["frontend", "react", "css"]

[[routing.rules]]
provider = "claude"
[routing.rules.match]
keywords = ["security", "architecture"]

# Caller detection
caller_override = ""
auto_exclude_caller = true

# Named profiles
[profiles.budget]
description = "Use cheaper models"
[profiles.budget.providers.codex]
model = "gpt-4.1-mini"
[profiles.budget.providers.gemini]
model = "gemini-2.5-flash"
```

### Policy Engine

Create `~/.config/vyane/policy.json`:

```json
{
  "allowed_providers": [],
  "blocked_providers": ["gemini"],
  "blocked_sandboxes": ["full"],
  "max_timeout": 600,
  "max_calls_per_hour": 30,
  "max_calls_per_day": 200
}
```

## Output Schema

All results follow the canonical schema:

```json
{
    "run_id": "a1b2c3d4",
    "provider": "codex",
    "status": "success",
    "summary": "First 200 chars...",
    "output": "Full model response",
    "session_id": "uuid-for-multi-turn",
    "duration_seconds": 12.5,
    "token_usage": {
        "input_tokens": 1200,
        "output_tokens": 340,
        "total_tokens": 1540
    },
    "routed_from": "auto",
    "caller_excluded": "claude"
}
```

`token_usage` is included when the provider returns token data (Codex, Gemini). Cost estimation is available via `mux_history(costs=True)`.

## Features

| Feature | Description |
|---------|-------------|
| **Smart Routing v4** | Keyword + history + benchmark + user feedback scoring |
| **Failover + Retry** | Exponential backoff retry, then auto-failover to next provider |
| **CLI Dispatch** | `vyane dispatch` / `broadcast` for scripts, CI, and pipelines |
| **GitHub Actions** | Reusable composite action for automated PR code review |
| **Profiles** | Named configs for model/API overrides (budget, china, etc.) |
| **Multi-turn** | Session continuity via native CLI session IDs |
| **Broadcast** | Parallel dispatch to multiple providers with comparison |
| **Collaboration** | Iterative multi-agent patterns (review, consensus, debate) |
| **Workflows** | Multi-step pipeline chains with variable substitution |
| **Cost Tracking** | Token usage extraction + per-model cost estimation |
| **A2A Protocol** | HTTP server + client for agent-to-agent interop |
| **User Feedback** | Rate results 1-5 to improve routing quality over time |
| **Web Dashboard** | Real-time monitoring with charts and feedback panel |
| **Policy Engine** | Rate limits, provider/sandbox blocking |
| **Custom Plugins** | User-defined adapters + A2A remote agents via config |

## GitHub Actions

Automated PR code review using Vyane:

```yaml
# .github/workflows/review.yml
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pure-maple/vyane/.github/actions/review@main
        with:
          provider: auto  # or codex, gemini, claude, dashscope
```

The action extracts the PR diff, dispatches it for review, and posts the result as a PR comment.

## Design Decisions

Architecture jointly designed through multi-model consultation:
- **Claude Opus 4.6** — original proposal and synthesis
- **GPT-5.3-Codex** — recommended unified hub, OPA policy engine
- **Gemini-3.1-Pro-Preview** — recommended A2A protocol backbone

Key consensus: one unified MCP hub (not 3 bridges), MCP-first (no Bash permissions needed), canonical output schema, session continuity, code sovereignty.

See `references/consultation/` for full records.

## License

MIT
