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

Quick Start

Give Your Agent Durable Memory

Victor pairs with ProximaDB — a multi-model (vector + graph + document) context database by the same author — as its durable memory layer. Index any repository with the shared 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 — Docker + two pip installs, ~10 minutes.

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) is roadmap, not shipped — see the roadmap and ProximaDB as the CCG Backend.

Python API

from victor.framework import Agent, EventType, ToolSet

agent = await Agent.create(
    provider="anthropic",
    tools=ToolSet.default(),
)

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

StateGraph Workflows

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)

result = await graph.compile().invoke({"query": "review this module", "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.

Victor 0.7 makes the framework/plugin split explicit:

• 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.

Detailed references:

• Architecture overview
• Internal architecture diagram
• contracts boundary
• State-passed architecture

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.

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 uses a two-database model:

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

python -m venv .venv
source .venv/bin/activate
# victor-contracts first so victor-ai resolves the in-repo SDK, not PyPI
pip install -e ./victor-contracts -e ".[dev]"

make test-quick
make test
make lint
make check-repo-hygiene

Optional extras

The base install degrades gracefully when optional dependencies are absent (lazy/guarded imports). Install an extra only when you want that capability:

pip install -e ".[web]"          # headless browser rendering + trafilatura extraction
                                #   (web_fetch render=browser; DDG browser fallback)
                                #   then: playwright install chromium
pip install -e ".[embeddings]"   # sentence-transformers + lancedb for semantic search
pip install -e ".[docker]"       # sandboxed code execution / container deploy
pip install -e ".[langchain]"    # adapt LangChain tools as native Victor tools

Subprojects are scoped:

npm --prefix vscode-victor run compile
cd rust && cargo test

Documentation

• Getting Started
• Durable Code Memory with ProximaDB
• Guides
• Reference
• Development
• Architecture
• Roadmap

Contributing

Start with CONTRIBUTING.md and the architecture overview; see the development docs 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.