Metadata-Version: 2.4
Name: victor-ai
Version: 0.9.5
Summary: Open-source agentic AI framework with multi-provider support, workflow orchestration, and extensible tool system
Author-email: Vijaykumar Singh <vijay@anvaiops.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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: victor-contracts<1.0,>=0.9.2
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: orjson>=3.9.0
Requires-Dist: sandhi-gateway==0.7.0
Requires-Dist: packaging>=23.0
Requires-Dist: numpy<2.3,>=1.24
Requires-Dist: cvss<4,>=3.6
Requires-Dist: httpx>=0.27
Requires-Dist: aiofiles>=23.0
Requires-Dist: aiohttp>=3.14.3
Requires-Dist: typer<0.26,>=0.15
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: 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.20.0
Requires-Dist: cachetools>=5.3
Requires-Dist: docstring-parser>=0.15
Requires-Dist: psutil>=5.9
Provides-Extra: docker
Requires-Dist: docker>=7.0; extra == "docker"
Provides-Extra: embeddings
Requires-Dist: numpy<2.3,>=1.24; extra == "embeddings"
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: torch>=2.13.0; extra == "embeddings"
Requires-Dist: lancedb>=0.6.0; extra == "embeddings"
Requires-Dist: pyarrow>=14.0; extra == "embeddings"
Provides-Extra: proximadb
Requires-Dist: proximadb<0.4,>=0.3; extra == "proximadb"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Provides-Extra: gateway
Requires-Dist: fastapi>=0.109; extra == "gateway"
Requires-Dist: uvicorn>=0.27; extra == "gateway"
Provides-Extra: examples
Provides-Extra: web
Requires-Dist: playwright>=1.40; extra == "web"
Requires-Dist: trafilatura>=1.6; extra == "web"
Provides-Extra: chat-ui
Requires-Dist: chainlit<3,>=2; extra == "chat-ui"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.4; extra == "ml"
Requires-Dist: scipy>=1.10; extra == "ml"
Provides-Extra: dev
Requires-Dist: numpy<2.3,>=1.24; extra == "dev"
Requires-Dist: sentence-transformers>=2.2.0; extra == "dev"
Requires-Dist: torch>=2.13.0; extra == "dev"
Requires-Dist: lancedb>=0.6.0; extra == "dev"
Requires-Dist: pyarrow>=14.0; extra == "dev"
Requires-Dist: Levenshtein>=0.25.1; 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-timeout>=2.3; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: aiosqlite>=0.19; extra == "dev"
Requires-Dist: docker>=7.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: ruff==0.15.20; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: black==26.3.1; extra == "dev"
Requires-Dist: radon>=6.0; extra == "dev"
Requires-Dist: types-pyyaml; extra == "dev"
Requires-Dist: types-aiofiles; extra == "dev"
Requires-Dist: strawberry-graphql[fastapi]>=0.243; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: tree-sitter-python>=0.23; extra == "dev"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "dev"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "dev"
Requires-Dist: tree-sitter-go>=0.23; extra == "dev"
Requires-Dist: tree-sitter-rust>=0.23; extra == "dev"
Requires-Dist: tree-sitter-java>=0.23; extra == "dev"
Requires-Dist: tree-sitter-cpp>=0.23; extra == "dev"
Requires-Dist: tree-sitter-c>=0.23; extra == "dev"
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "dev"
Requires-Dist: tree-sitter-ruby>=0.23; extra == "dev"
Requires-Dist: tree-sitter-php>=0.24; extra == "dev"
Requires-Dist: tree-sitter-swift>=0.0.1; extra == "dev"
Requires-Dist: tree-sitter-scala>=0.23; extra == "dev"
Requires-Dist: tree-sitter-kotlin>=1.0; extra == "dev"
Requires-Dist: tree-sitter-bash>=0.23; extra == "dev"
Requires-Dist: tree-sitter-lua>=0.2; extra == "dev"
Requires-Dist: tree-sitter-elixir>=0.3; extra == "dev"
Requires-Dist: tree-sitter-haskell>=0.23; extra == "dev"
Provides-Extra: ci
Requires-Dist: numpy<2.3,>=1.24; extra == "ci"
Requires-Dist: sentence-transformers>=2.2.0; extra == "ci"
Requires-Dist: torch>=2.13.0; extra == "ci"
Requires-Dist: lancedb>=0.6.0; extra == "ci"
Requires-Dist: pyarrow>=14.0; extra == "ci"
Requires-Dist: pytest>=8.0; extra == "ci"
Requires-Dist: pytest-asyncio>=0.23; extra == "ci"
Requires-Dist: pytest-cov>=4.1; extra == "ci"
Requires-Dist: pytest-mock>=3.12; extra == "ci"
Requires-Dist: pytest-json-report>=1.5.0; extra == "ci"
Requires-Dist: pytest-benchmark>=5.0; extra == "ci"
Requires-Dist: pytest-timeout>=2.3; extra == "ci"
Requires-Dist: pytest-xdist>=3.5; extra == "ci"
Requires-Dist: respx>=0.21; extra == "ci"
Requires-Dist: pandas>=2.0; extra == "ci"
Requires-Dist: docker>=7.0; extra == "ci"
Requires-Dist: scipy>=1.10; extra == "ci"
Requires-Dist: scikit-learn>=1.4; extra == "ci"
Requires-Dist: ruff==0.15.20; extra == "ci"
Requires-Dist: mypy>=1.10; extra == "ci"
Requires-Dist: black==26.3.1; extra == "ci"
Requires-Dist: radon>=6.0; extra == "ci"
Requires-Dist: types-pyyaml; extra == "ci"
Requires-Dist: types-aiofiles; extra == "ci"
Requires-Dist: pytest-split>=0.8; extra == "ci"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "ci"
Requires-Dist: tree-sitter-python>=0.23; extra == "ci"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "ci"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "ci"
Requires-Dist: tree-sitter-go>=0.23; extra == "ci"
Requires-Dist: tree-sitter-rust>=0.23; extra == "ci"
Requires-Dist: tree-sitter-java>=0.23; extra == "ci"
Requires-Dist: tree-sitter-cpp>=0.23; extra == "ci"
Requires-Dist: tree-sitter-c>=0.23; extra == "ci"
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "ci"
Requires-Dist: tree-sitter-ruby>=0.23; extra == "ci"
Requires-Dist: tree-sitter-php>=0.24; extra == "ci"
Requires-Dist: tree-sitter-swift>=0.0.1; extra == "ci"
Requires-Dist: tree-sitter-scala>=0.23; extra == "ci"
Requires-Dist: tree-sitter-kotlin>=1.0; extra == "ci"
Requires-Dist: tree-sitter-bash>=0.23; extra == "ci"
Requires-Dist: tree-sitter-lua>=0.2; extra == "ci"
Requires-Dist: tree-sitter-elixir>=0.3; extra == "ci"
Requires-Dist: tree-sitter-haskell>=0.23; 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: 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"
Requires-Dist: pygments>=2.20.0; 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"
Requires-Dist: pygments>=2.20.0; 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: myst-parser>=2.0.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-core
Requires-Dist: tree-sitter-python>=0.23; extra == "lang-core"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "lang-core"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "lang-core"
Requires-Dist: tree-sitter-go>=0.23; extra == "lang-core"
Requires-Dist: tree-sitter-rust>=0.23; extra == "lang-core"
Requires-Dist: tree-sitter-java>=0.23; extra == "lang-core"
Requires-Dist: tree-sitter-cpp>=0.23; extra == "lang-core"
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-python>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-go>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-rust>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-java>=0.23; extra == "lang-all"
Requires-Dist: tree-sitter-cpp>=0.23; 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; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "apple-silicon"
Provides-Extra: native
Requires-Dist: victor-native>=0.8.1; extra == "native"
Provides-Extra: coding
Requires-Dist: victor-coding<1.0.0,>=0.6.0; extra == "coding"
Requires-Dist: tree-sitter-python>=0.23; extra == "coding"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "coding"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "coding"
Requires-Dist: tree-sitter-go>=0.23; extra == "coding"
Requires-Dist: tree-sitter-rust>=0.23; extra == "coding"
Requires-Dist: tree-sitter-java>=0.23; extra == "coding"
Requires-Dist: tree-sitter-cpp>=0.23; extra == "coding"
Provides-Extra: research
Requires-Dist: victor-research<1.0.0,>=0.6.0; extra == "research"
Provides-Extra: devops
Requires-Dist: victor-devops<1.0.0,>=0.6.0; extra == "devops"
Provides-Extra: invest
Requires-Dist: victor-invest<1.0.0,>=0.5.0; extra == "invest"
Provides-Extra: verticals
Requires-Dist: victor-coding<1.0.0,>=0.6.0; extra == "verticals"
Requires-Dist: victor-research<1.0.0,>=0.6.0; extra == "verticals"
Requires-Dist: victor-devops<1.0.0,>=0.6.0; extra == "verticals"
Requires-Dist: victor-invest<1.0.0,>=0.5.0; extra == "verticals"
Provides-Extra: all
Requires-Dist: victor-ai[apple-silicon,build,dev,docs,lang-all]; extra == "all"
Dynamic: license-file

<div align="center">

# Victor

**A contract-first agentic AI framework for building reliable agents across local and cloud models.**

[![PyPI version](https://badge.fury.io/py/victor-ai.svg)](https://pypi.org/project/victor-ai/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Fast Checks](https://github.com/anvai-labs/victor/actions/workflows/ci-fast.yml/badge.svg)](https://github.com/anvai-labs/victor/actions/workflows/ci-fast.yml)
[![Tests](https://github.com/anvai-labs/victor/actions/workflows/ci-test.yml/badge.svg)](https://github.com/anvai-labs/victor/actions/workflows/ci-test.yml)
[![Documentation](https://github.com/anvai-labs/victor/actions/workflows/docs.yml/badge.svg)](https://anvai-labs.github.io/victor/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/docker-victor--ai-blue.svg)](https://hub.docker.com/r/vjsingh1984/victor-ai)

</div>

---

Victor gives you a typed Python framework, a service-first agent runtime, and a contract-first plugin ecosystem for building agents that can reason, call tools, run workflows, coordinate teams, and operate against project-local code intelligence.

It is designed for teams that need agent systems to be testable, extensible, observable, and portable across Anthropic, OpenAI-compatible providers, Gemini, Bedrock, local models, and air-gapped environments.

## Why Victor

| Capability | What it gives you |
|------------|-------------------|
| **Service-first runtime** | Focused service interfaces for chat, tools, sessions, context, provider routing, and recovery. |
| **StateGraph workflows** | Compile definitions into one execution engine for tasks, streaming, conditional routing, teams and checkpoints. |
| **Verified native paths** | Optional Rust acceleration with required CI parity checks against Python behavior. |
| **Local and cloud models** | Use cloud providers for capability, local providers for privacy/cost, and provider-specific caching strategies for performance. |
| **Tool-rich execution** | Compose filesystem, git, shell, code search, graph, verification, Docker, web, testing, and refactoring tools. |
| **Contract-first plugins** | Put domain behavior in sibling `victor-*` packages through `victor-contracts` and public framework extension contracts. |
| **Project code intelligence** | Keep graph indexes, semantic search, conversations, and project memory in project-local state. |

## Quick Start

| Path | Commands | Best for |
|------|----------|----------|
| Local model | `pipx install victor-ai`<br>`ollama pull qwen2.5-coder:7b`<br>`victor chat --provider ollama --model qwen2.5-coder:7b "Explain this repo"` | Private, low-cost, air-gapped work |
| Cloud model | `pipx install victor-ai`<br>`export ANTHROPIC_API_KEY=...`<br>`victor chat --provider anthropic "Plan this refactor"` | Hosted provider access |
| Python API | `pip install victor-ai` | Embedding Victor in applications |
| Docker | `docker pull vjsingh1984/victor-ai:latest` | Isolated CLI/API runtime |

## Give Your Agent Durable Memory

Victor supports [ProximaDB](https://github.com/anvai-labs/proximaDB) as an optional
backend for durable code memory. Index any repository with the shared [`victor-codegraph`](victor-codegraph/)
chunker and get semantic recall ("where do we validate JWTs?") plus call-graph queries
("who calls `parse_jwt`?") that persist across sessions:

**[Quickstart: Durable Code Memory with ProximaDB](docs/quickstart-proximadb-memory.md)** — setup, indexing, semantic recall and graph queries.

Victor's embedded ProximaDB backends for project code intelligence are experimental,
flag-gated previews — SQLite/LanceDB remain the defaults. The correlated graph+vector
code-context backend (one entity = row + graph node + vector, TD-11/12/13) has
implemented opt-in correlation and routing; benchmark, service-mode and default-graduation
work remains — see the [roadmap](docs/roadmap.md) and
[ProximaDB as the CCG Backend](docs/architecture/proximadb-codegraph-backend.md).

## Python API

```python
import asyncio

from victor.framework import Agent, EventType, ToolSet


async def main():
    async with await Agent.create(
        provider="anthropic",
        tools=ToolSet.default(),
    ) as agent:
        result = await agent.run("Explain the architecture of this codebase")
        print(result.content)

        async for event in agent.stream("Review the changed files"):
            if event.type == EventType.CONTENT:
                print(event.content, end="", flush=True)


asyncio.run(main())
```

## StateGraph Workflows

```python
import asyncio
from typing import TypedDict

from victor.framework import END, StateGraph


class ReviewState(TypedDict):
    query: str
    findings: list[str]


async def inspect(state: ReviewState) -> ReviewState:
    return {**state, "findings": ["example finding"]}


graph = StateGraph(ReviewState)
graph.add_node("inspect", inspect)
graph.add_edge("inspect", END)
graph.set_entry_point("inspect")

result = asyncio.run(
    graph.compile().invoke({"query": "review this module", "findings": []})
)
print(result.state["findings"])
```

## Architecture

The core rule is simple: interfaces compose framework APIs, framework APIs delegate to the service-first runtime, and domain packages plug in through SDK/public extension contracts.

```mermaid
---
title: Victor system overview
---
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#E8EFF7","primaryTextColor":"#17324D","primaryBorderColor":"#456987","lineColor":"#456987","fontFamily":"Arial"}}}%%
flowchart TB
  C["Clients<br/>CLI · TUI · HTTP · MCP · VS Code"]
  F["Framework<br/>VictorClient · AgentFactory<br/>Agent · WorkflowEngine · StateGraph"]
  R["Runtime<br/>AgentOrchestrator facade<br/>chat, tool and session services"]
  I["Infrastructure<br/>providers · tools · storage · core"]
  V["External vertical definitions"]
  S["victor_contracts"]
  C -->|"call public APIs"| F
  F -->|"construct and delegate"| R
  R -->|"perform effectful operations"| I
  V -->|"declare capabilities"| S
  F -.->|"consume contracts"| S
```

The [canonical architecture guide](docs/architecture.md) explains the boundaries and execution paths.
Workflow execution and streaming share `CompiledGraph`; the former BFS walker has been removed.
The unified streaming chat loop is implemented. Further chat ownership inversion, expanded
interrupt/resume semantics and RL package relocation remain explicitly labelled proposal targets.

The framework/plugin split is:

- `victor.framework` is the stable public contract for agents, tools, StateGraph, workflows, events, and extension surfaces.
- `victor.agent` is the internal runtime implementation behind that contract.
- `victor.agent.services` owns effectful runtime behavior through `ChatService`, `ToolService`, `SessionService`, `ContextService`, `ProviderService`, and `RecoveryService`.
- `victor-contracts` is the definition-layer contract for external verticals and plugins.
- Sibling `victor-*` packages own domain behavior such as coding, DevOps, RAG, research, data analysis, and investment workflows.

Read the [published documentation](https://anvai-labs.github.io/victor/) for navigation and searchable API references.

Detailed references:

- [Architecture overview](docs/architecture.md)
- [Diagram map and refresh audit](docs/diagrams/refresh-2026-09.md)
- [contracts boundary](docs/architecture/CONTRACTS_BOUNDARY.md)
- [State-passed architecture](docs/architecture/state-passed-architecture.md)

## Plugin Ecosystem

External and first-party domain packages should use `victor-contracts` and public framework extension contracts. The root framework stays generic; domain-specific behavior belongs in plugins and vertical packages.

| Package | Focus |
|---------|-------|
| `victor-coding` | Code review, editing, test generation, language tooling |
| `victor-devops` | Infrastructure, containers, CI/CD, cloud operations |
| `victor-rag` | Ingestion, retrieval, hybrid search, grounded answers |
| `victor-dataanalysis` | Data cleaning, statistics, dataframe analysis, visualization |
| `victor-research` | Source research, synthesis, fact checking |
| `victor-invest` | Investment research workflows and dashboard/API integration |
| `victor-registry` | Package marketplace and registry metadata |

Plugin rules:

- Use the `victor.plugins` entry point as the canonical discovery seam.
- Register capabilities through `VictorPlugin.register(context)`.
- Import from `victor_contracts`, `victor.framework.extensions`, or documented public APIs.
- Do not import `victor.agent.*` or private root runtime internals from external packages.

## Use Cases

- Build local or cloud-backed coding agents that can inspect files, search graphs, run tests, and produce review findings.
- Compose workflow agents with typed StateGraph nodes, deterministic handoffs, and resumable execution.
- Run tool-using assistants through CLI, TUI, HTTP API, MCP, or embedded Python.
- Build domain plugins without copying framework internals into vertical packages.
- Keep project code intelligence local while preserving global preferences, learning, and provider settings separately.

## State and Code Intelligence

Victor separates global and project state, with a dedicated database for undo history:

| Scope | Location | Purpose |
|-------|----------|---------|
| Global database | `~/.victor/victor.db` | Settings, API keys, profiles, RL outcomes, tool/model preferences, cross-project patterns |
| Project database | `./.victor/project.db` | Graph nodes/edges, conversations, project sessions, entity memory, change tracking |
| Undo database | `./.victor/undo.db` | File-edit undo/redo history, isolated from indexer write locks |

Project code intelligence is derived, rebuildable state. Graph indexes, vector indexes, file watcher state, and `.victor/` runtime artifacts should not become source-of-truth release artifacts.

## Development

Follow [Development Setup](docs/development/setup.md) for the environment, optional extras,
[native extension build](docs/development/setup.md#native-extension-build), and
[documentation preview](docs/development/setup.md#documentation-build). The
[PR workflow](docs/development/PR_WORKFLOW.md) defines verification and branch conventions.
Use [dependency maintenance](docs/development/dependencies.md) to choose deployment
extras, refresh resolved requirements, and build the core, MCP, native or full container target.

## Documentation

- [Documentation map](docs/index.md)
- [Canonical guide index](docs/README.md)
- [Getting Started](docs/getting-started/)
- [Durable Code Memory with ProximaDB](docs/quickstart-proximadb-memory.md)
- [Guides](docs/guides/)
- [Reference](docs/reference/)
- [Development](docs/development/)
- [Architecture](docs/architecture.md)
- [Roadmap](docs/roadmap.md)

## Contributing

Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [architecture overview](docs/architecture.md); see the [development docs](docs/development/) for setup, code style, and the PR workflow. Keep changes scoped, prefer public framework/SDK contracts over internal imports, and update docs/tests when public behavior changes.

## License

Apache License 2.0. See [LICENSE](LICENSE).
