Metadata-Version: 2.4
Name: victor-ai
Version: 0.6.0
Summary: Open-source agentic AI framework with multi-provider support, workflow orchestration, and extensible tool system
Author-email: Vijaykumar Singh <singhvjd@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/vijayksingh/victor
Project-URL: Documentation, https://github.com/vijayksingh/victor#readme
Project-URL: Repository, https://github.com/vijayksingh/victor
Project-URL: Issues, https://github.com/vijayksingh/victor/issues
Keywords: ai,llm,coding-agent,victor,anthropic,openai,ollama,claude,gpt,cli,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: victor-sdk==0.6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: typing-extensions>=4.9
Requires-Dist: httpx>=0.27
Requires-Dist: aiofiles>=23.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: textual>=0.89
Requires-Dist: anthropic>=0.34
Requires-Dist: openai>=1.40
Requires-Dist: gitpython>=3.1
Requires-Dist: jsonschema>=4.20
Requires-Dist: tiktoken>=0.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: lxml>=5.0
Requires-Dist: tree-sitter>=0.23
Requires-Dist: pygments>=2.17
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-rust>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-cpp>=0.23
Requires-Dist: cachetools>=5.3
Requires-Dist: diskcache>=5.6
Requires-Dist: docker>=7.0
Requires-Dist: docstring-parser>=0.15
Requires-Dist: psutil>=5.9
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: lancedb>=0.6.0; extra == "embeddings"
Requires-Dist: pyarrow>=14.0; extra == "embeddings"
Provides-Extra: examples
Provides-Extra: dev
Requires-Dist: victor[embeddings]; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: pytest-json-report>=1.5.0; extra == "dev"
Requires-Dist: pytest-benchmark>=5.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: black==26.1.0; extra == "dev"
Requires-Dist: types-pyyaml; extra == "dev"
Requires-Dist: types-aiofiles; extra == "dev"
Requires-Dist: strawberry-graphql[fastapi]>=0.243; extra == "dev"
Provides-Extra: ci
Requires-Dist: victor[dev]; extra == "ci"
Requires-Dist: pytest-split>=0.8; extra == "ci"
Requires-Dist: build>=0.10; extra == "ci"
Requires-Dist: wheel>=0.42; extra == "ci"
Requires-Dist: twine>=4.0; extra == "ci"
Requires-Dist: strawberry-graphql[fastapi]>=0.243; extra == "ci"
Requires-Dist: scipy>=1.10; extra == "ci"
Requires-Dist: pytest-cov>=4.1; extra == "ci"
Requires-Dist: codecov>=2.1; extra == "ci"
Requires-Dist: pre-commit>=3.5; extra == "ci"
Requires-Dist: bandit>=1.7; extra == "ci"
Requires-Dist: detect-secrets>=1.4; extra == "ci"
Requires-Dist: mkdocs>=1.5; extra == "ci"
Requires-Dist: mkdocs-material>=9.5; extra == "ci"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "ci"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: sphinx-docs
Requires-Dist: sphinx>=7.0.0; extra == "sphinx-docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0.0; extra == "sphinx-docs"
Requires-Dist: sphinxcontrib-apidoc>=0.5.0; extra == "sphinx-docs"
Requires-Dist: sphinx-napoleon>=0.9; extra == "sphinx-docs"
Requires-Dist: sphinx-viewcode>=2.0; extra == "sphinx-docs"
Requires-Dist: sphinx-intersphinx>=2.0; extra == "sphinx-docs"
Requires-Dist: sphinx-duration>=0.2; extra == "sphinx-docs"
Requires-Dist: sphinx-doctest>=1.0; extra == "sphinx-docs"
Requires-Dist: sphinx-coverage>=2.0; extra == "sphinx-docs"
Requires-Dist: furo>=2023.0.0; extra == "sphinx-docs"
Requires-Dist: sphinx-autobuild>=2023.0.0; extra == "sphinx-docs"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == "build"
Requires-Dist: pyinstaller-hooks-contrib>=2024.0; extra == "build"
Provides-Extra: api
Requires-Dist: fastapi>=0.109; extra == "api"
Requires-Dist: uvicorn>=0.27; extra == "api"
Requires-Dist: strawberry-graphql[fastapi]>=0.243; extra == "api"
Provides-Extra: checkpoints
Requires-Dist: aiosqlite>=0.19; extra == "checkpoints"
Provides-Extra: google
Requires-Dist: google-genai>=1.0; extra == "google"
Provides-Extra: lang-c
Requires-Dist: tree-sitter-c>=0.23; extra == "lang-c"
Provides-Extra: lang-csharp
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "lang-csharp"
Provides-Extra: lang-ruby
Requires-Dist: tree-sitter-ruby>=0.23; extra == "lang-ruby"
Provides-Extra: lang-php
Requires-Dist: tree-sitter-php>=0.24; extra == "lang-php"
Provides-Extra: lang-swift
Requires-Dist: tree-sitter-swift>=0.0.1; extra == "lang-swift"
Provides-Extra: lang-scala
Requires-Dist: tree-sitter-scala>=0.23; extra == "lang-scala"
Provides-Extra: lang-kotlin
Requires-Dist: tree-sitter-kotlin>=1.0; extra == "lang-kotlin"
Provides-Extra: lang-bash
Requires-Dist: tree-sitter-bash>=0.23; extra == "lang-bash"
Provides-Extra: lang-lua
Requires-Dist: tree-sitter-lua>=0.2; extra == "lang-lua"
Provides-Extra: lang-elixir
Requires-Dist: tree-sitter-elixir>=0.3; extra == "lang-elixir"
Provides-Extra: lang-haskell
Requires-Dist: tree-sitter-haskell>=0.23; extra == "lang-haskell"
Provides-Extra: lang-sql
Requires-Dist: tree-sitter-sql>=0.3; extra == "lang-sql"
Provides-Extra: lang-html
Requires-Dist: tree-sitter-html>=0.23; extra == "lang-html"
Provides-Extra: lang-css
Requires-Dist: tree-sitter-css>=0.23; extra == "lang-css"
Provides-Extra: lang-json
Requires-Dist: tree-sitter-json>=0.23; extra == "lang-json"
Provides-Extra: lang-yaml
Requires-Dist: tree-sitter-yaml>=0.6; extra == "lang-yaml"
Provides-Extra: lang-toml
Requires-Dist: tree-sitter-toml>=0.6; extra == "lang-toml"
Provides-Extra: lang-markdown
Requires-Dist: tree-sitter-markdown>=0.5; extra == "lang-markdown"
Provides-Extra: lang-xml
Requires-Dist: tree-sitter-xml>=0.6; extra == "lang-xml"
Provides-Extra: lang-web
Requires-Dist: tree-sitter-html>=0.23; extra == "lang-web"
Requires-Dist: tree-sitter-css>=0.23; extra == "lang-web"
Requires-Dist: tree-sitter-json>=0.23; extra == "lang-web"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "lang-web"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "lang-web"
Provides-Extra: lang-config
Requires-Dist: tree-sitter-json>=0.23; extra == "lang-config"
Requires-Dist: tree-sitter-yaml>=0.6; extra == "lang-config"
Requires-Dist: tree-sitter-toml>=0.6; extra == "lang-config"
Requires-Dist: tree-sitter-xml>=0.6; extra == "lang-config"
Requires-Dist: tree-sitter-markdown>=0.5; extra == "lang-config"
Provides-Extra: lang-jvm
Requires-Dist: tree-sitter-scala>=0.23; extra == "lang-jvm"
Requires-Dist: tree-sitter-kotlin>=1.0; extra == "lang-jvm"
Requires-Dist: tree-sitter-java>=0.23; extra == "lang-jvm"
Provides-Extra: lang-systems
Requires-Dist: tree-sitter-c>=0.23; extra == "lang-systems"
Requires-Dist: tree-sitter-bash>=0.23; extra == "lang-systems"
Requires-Dist: tree-sitter-cpp>=0.23; extra == "lang-systems"
Provides-Extra: lang-apple
Requires-Dist: tree-sitter-swift>=0.0.1; extra == "lang-apple"
Provides-Extra: lang-dotnet
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "lang-dotnet"
Provides-Extra: lang-scripting
Requires-Dist: tree-sitter-ruby>=0.23; extra == "lang-scripting"
Requires-Dist: tree-sitter-php>=0.24; extra == "lang-scripting"
Requires-Dist: tree-sitter-lua>=0.2; extra == "lang-scripting"
Provides-Extra: lang-functional
Requires-Dist: tree-sitter-elixir>=0.3; extra == "lang-functional"
Requires-Dist: tree-sitter-haskell>=0.23; extra == "lang-functional"
Requires-Dist: tree-sitter-scala>=0.23; extra == "lang-functional"
Provides-Extra: lang-all
Requires-Dist: tree-sitter-c>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-ruby>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-php>=0.24; extra == "lang-all"
Requires-Dist: tree-sitter-swift>=0.0.1; extra == "lang-all"
Requires-Dist: tree-sitter-scala>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-kotlin>=1.0; extra == "lang-all"
Requires-Dist: tree-sitter-bash>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-lua>=0.2; extra == "lang-all"
Requires-Dist: tree-sitter-elixir>=0.3; extra == "lang-all"
Requires-Dist: tree-sitter-haskell>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-sql>=0.3; extra == "lang-all"
Requires-Dist: tree-sitter-html>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-css>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-json>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-yaml>=0.6; extra == "lang-all"
Requires-Dist: tree-sitter-toml>=0.6; extra == "lang-all"
Requires-Dist: tree-sitter-markdown>=0.5; extra == "lang-all"
Requires-Dist: tree-sitter-xml>=0.6; extra == "lang-all"
Provides-Extra: apple-silicon
Requires-Dist: mlx-lm>=0.21.0; extra == "apple-silicon"
Provides-Extra: native
Requires-Dist: maturin>=1.4; extra == "native"
Provides-Extra: rag
Provides-Extra: coding
Provides-Extra: research
Provides-Extra: devops
Provides-Extra: dataanalysis
Provides-Extra: verticals
Provides-Extra: all
Requires-Dist: victor[apple-silicon,build,dev,docs,lang-all]; extra == "all"
Dynamic: license-file

<div align="center">

# Victor

**Open-source agentic AI framework. Build, orchestrate, and evaluate AI agents across 22 providers.**

[![PyPI version](https://badge.fury.io/py/victor-ai.svg)](https://pypi.org/project/victor-ai/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Tests](https://github.com/vjsingh1984/victor/actions/workflows/test.yml/badge.svg)](https://github.com/vjsingh1984/victor/actions/workflows/test.yml)
[![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen.svg)](https://github.com/vjsingh1984/victor/actions)
[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/vjsingh1984/victor)

</div>

---

## Features

```
┌─────────────────────────────────────────────────────────────┐
│                     VICTOR FRAMEWORK                        │
│                                                             │
│  Agents ─── Teams ─── Workflows ─── Evaluation              │
│    │          │          │              │                    │
│  run()    Sequential   StateGraph    SWE-bench              │
│  stream()  Parallel    YAML DSL      Harnesses              │
│  chat()   Hierarchical Checkpoints   Code Quality           │
│           Pipeline                                          │
│                                                             │
│  24 Providers │ 34 Tool Modules │ 9 Verticals │ 4 Scopes   │
└─────────────────────────────────────────────────────────────┘
```

- **24 LLM Providers** — Cloud (Anthropic, OpenAI, Google, Azure, Bedrock, DeepSeek, Vertex) + local (Ollama, LM Studio, vLLM)
- **34 Tool Modules** — File ops, git, shell, web, search, docker, testing, refactoring, analysis
- **9 Domain Verticals** — Coding, DevOps, RAG, Data Analysis, Research, Security, IaC, Classification, Benchmark
- **Multi-Agent Teams** — 4 formations: sequential, parallel, hierarchical, pipeline
- **Stateful Workflows** — YAML DSL compiled to StateGraph with typed state and checkpointing
- **Air-Gapped Mode** — Full functionality with local models for secure, offline environments
- **Built-in Resilience** — Automatic retry with exponential backoff on rate limits, circuit breaker protection

### Benchmark Results (March 2026)

Victor achieves **100% task success rate** across multiple providers:

| Provider | Model | 5-Task Success | Avg Time/Task | Cost/1M tokens |
|----------|-------|---------------|--------------|----------------|
| Anthropic | Claude Haiku 4.5 | **100%** | 16.9s | $0.80 in |
| OpenAI | GPT-4o-mini | **100%** | 14.7s | $0.15 in |
| DeepSeek | DeepSeek-Chat V3 | **100%** | 35.9s | $0.07 in |

> Tasks: code generation, research synthesis, file operations, security audit, workflow orchestration.
> See [full results](docs/benchmarking/results/BENCHMARK_RESULTS_2026-03-16.md)

## At a glance

```
                              ┌─────────────────────────────────┐
                              │       Agent Orchestrator        │
                              │                                 │
[You] ──▶ [CLI/TUI/API] ──▶  │  ProviderManager ──▶ 24 LLMs   │ ──▶ [Response]
                              │  ToolPipeline    ──▶ 34 Tools   │
                              │  TeamCoordinator ──▶ Agents     │
                              │  StateManager    ──▶ 4 Scopes   │
                              └─────────────────────────────────┘
```

## Choose your path

| Persona | Start here | Typical goals |
|---------|------------|---------------|
| **New user** | [Getting Started](docs/getting-started/) | Install, first run, local vs cloud |
| **Daily user** | [User Guide](docs/user-guide/) | Commands, modes, profiles, workflows |
| **Operator** | [Operations](docs/operations/) | Deployment, monitoring, security |
| **Contributor** | [Development](docs/development/) | Setup, testing, architecture, extending |
| **Architect** | [Architecture](ARCHITECTURE.md) | System overview, core components |

## Quick start

| Path | Commands | Best for |
|------|----------|----------|
| **Local model** | `pipx install victor-ai`<br>`ollama pull qwen2.5-coder:7b`<br>`victor chat "Hello"` | Privacy, offline, free tier |
| **Cloud model** | `pipx install victor-ai`<br>`export ANTHROPIC_API_KEY=...`<br>`victor chat --provider anthropic` | Max capability |
| **Docker** | `docker pull ghcr.io/vjsingh1984/victor:latest`<br>`docker run -it -v ~/.victor:/root/.victor ghcr.io/vjsingh1984/victor:latest` | Isolated env |

## Supported Providers

Victor supports **22 LLM providers** — switch mid-conversation without losing context.

| Category | Providers |
|----------|-----------|
| **Frontier Cloud** | Anthropic, OpenAI, Google Gemini, Azure OpenAI |
| **Cloud Platforms** | AWS Bedrock, Google Vertex |
| **Specialized** | xAI, DeepSeek, Mistral, Groq, Cerebras, Moonshot, ZAI |
| **Aggregators** | OpenRouter, Together AI, Fireworks AI, Replicate, Hugging Face |
| **Local (air-gapped)** | Ollama, LM Studio, vLLM, llama.cpp |

[Full Provider Reference](docs/reference/providers/)

## Python API

Victor provides a clean Python API for programmatic use:

```python
from victor.framework import Agent, EventType

# Simple use case
agent = await Agent.create(provider="anthropic")
result = await agent.run("Explain this codebase structure")
print(result.content)

# Streaming responses
async for event in agent.stream("Refactor this function"):
    if event.type == EventType.CONTENT:
        print(event.content, end="")
    elif event.type == EventType.TOOL_CALL:
        print(f"\nUsing tool: {event.tool_name}")

# With tool configuration
from victor.framework import ToolSet

agent = await Agent.create(
    provider="openai",
    model="gpt-4o",
    tools=ToolSet.default()  # or ToolSet.minimal(), ToolSet.full()
)

# Multi-turn conversation
session = agent.chat()
await session.send("What files are in this project?")
await session.send("Now explain the main entry point")
```

### StateGraph Workflows

```python
from victor.framework import StateGraph, END
from typing import TypedDict

class MyState(TypedDict):
    query: str
    result: str

graph = StateGraph(MyState)

graph.add_node("research", research_fn)
graph.add_node("synthesize", synthesize_fn)

graph.add_edge("research", "synthesize")
graph.add_edge("synthesize", END)

compiled = graph.compile()
result = await compiled.invoke({"query": "AI trends 2025"})
```

## Core capabilities

| Capability | What it means | Docs |
|------------|---------------|------|
| **Agent abstractions** | `run()`, `stream()`, `chat()`, `run_workflow()`, `run_team()` | [Framework](docs/development/architecture/) |
| **22 Providers** | Cloud + local LLMs; switch mid-thread without losing context | [Providers](docs/reference/providers/) |
| **33 Tool modules** | File ops, git, shell, web, search, docker, testing, analysis | [Tool catalog](docs/reference/tools/) |
| **Workflows** | YAML DSL compiled to StateGraph with typed state + checkpointing | [Workflows](docs/guides/workflow-development/) |
| **Multi-agent teams** | 4 formations: sequential, parallel, hierarchical, pipeline | [Multi-agent](docs/guides/multi-agent/) |
| **State management** | 4 scopes: workflow, conversation, team, global | [State](docs/development/architecture/) |
| **9 Verticals** | Domain-focused agents with tools, prompts, and workflows | [Verticals](docs/reference/verticals/) |
| **Evaluation** | Agent harnesses, code quality analysis, SWE-bench integration | [Evaluation](docs/development/) |

## Command quick reference

| Command | Purpose | Example |
|---------|---------|---------|
| `victor` | TUI mode | `victor` |
| `victor chat` | CLI mode | `victor chat "refactor this"` |
| `victor chat --mode plan` | Plan-only analysis | `victor chat --mode plan` |
| `victor serve` | HTTP API | `victor serve --port 8080` |
| `victor mcp` | MCP server | `victor mcp --stdio` |
| `/provider` | Switch provider in chat | `/provider openai --model gpt-4` |

## Screenshots

<!-- TUI Screenshot -->
![Victor TUI](docs/assets/tui-screenshot.png)
*The Victor TUI provides an interactive terminal interface with syntax highlighting and tool status.*

<!-- CLI Screenshot -->
![Victor CLI](docs/assets/cli-screenshot.png)
*CLI mode for quick queries and script integration.*

## Documentation

- [Getting Started](docs/getting-started/)
- [User Guide](docs/user-guide/)
- [Guides](docs/guides/)
- [Reference](docs/reference/)
- [Operations](docs/operations/)
- [Development](docs/development/)
- [Architecture](ARCHITECTURE.md)
- [Roadmap](roadmap.md)

## Contributing

We welcome contributions. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## Community

- [GitHub](https://github.com/vjsingh1984/victor)
- [Discussions](https://github.com/vjsingh1984/victor/discussions)
- [Issues](https://github.com/vjsingh1984/victor/issues)
- [Discord](https://discord.gg/...)

## Acknowledgments

Victor is built on the shoulders of excellent open-source projects:

- **[Pydantic](https://docs.pydantic.dev/)** - Data validation and settings management
- **[Tree-sitter](https://tree-sitter.github.io/)** - Incremental parsing for code analysis
- **[Textual](https://textual.textualize.io/)** - Modern TUI framework
- **[Typer](https://typer.tiangolo.com/)** - CLI interface with type hints
- **[Rich](https://rich.readthedocs.io/)** - Beautiful terminal formatting
- **[httpx](https://www.python-httpx.org/)** - Async HTTP client
- **[Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python)** - Claude API client
- **[OpenAI SDK](https://github.com/openai/openai-python)** - OpenAI API client

## License

Apache License 2.0 - see [LICENSE](LICENSE).
