Metadata-Version: 2.4
Name: orvin
Version: 0.1.2
Summary: Orvin memory platform for voice agents
License-Expression: AGPL-3.0-only
Keywords: voice,memory,fastapi,mcp,cli,livekit,pipecat
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.32.0
Requires-Dist: typer<1.0.0,>=0.15.0
Requires-Dist: pydantic<3.0.0,>=2.9.0
Requires-Dist: pydantic-settings<3.0.0,>=2.6.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Requires-Dist: psycopg[binary]<4.0.0,>=3.2.0
Requires-Dist: sqlalchemy<3.0.0,>=2.0.36
Requires-Dist: pgvector<1.0.0,>=0.3.6
Requires-Dist: fastembed<1.0.0,>=0.7.0
Requires-Dist: pypdf<7.0.0,>=6.9.2
Requires-Dist: alembic<2.0.0,>=1.14.0
Requires-Dist: redis<6.0.0,>=5.2.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Provides-Extra: v2
Requires-Dist: usearch<3.0.0,>=2.12.0; extra == "v2"
Requires-Dist: lmdb<2.0.0,>=1.5.0; extra == "v2"
Requires-Dist: httpx<1.0.0,>=0.28.0; extra == "v2"
Provides-Extra: release
Requires-Dist: build<2.0.0,>=1.2.2; extra == "release"
Requires-Dist: twine<7.0.0,>=6.1.0; extra == "release"
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.2; extra == "dev"
Requires-Dist: fakeredis<3.0.0,>=2.31.0; extra == "dev"
Requires-Dist: httpx<1.0.0,>=0.28.0; extra == "dev"
Requires-Dist: numpy<3.0.0,>=1.26.0; extra == "dev"
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.24.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.1.0; extra == "dev"
Dynamic: license-file

# Orvin

Backend for a voice-native memory service for voice AI agents, wired for Neon-backed Postgres, local open-source embeddings, and local Redis.

Current rebuild docs for the next architecture step live in [`docs/README.md`](docs/README.md).
Multi-agent voice integration guidance lives in [`docs/voice-agent-integration.md`](docs/voice-agent-integration.md).

The target product abstraction is channel-agnostic:

- voice agents are the core product surface
- interactions are the core runtime unit
- calls are one supported channel, not the main product definition

## Stack

- FastAPI
- Python 3.12+
- Neon Postgres + pgvector
- Local Redis (working memory and context cache)
- FastEmbed with `BAAI/bge-small-en-v1.5` (local open-source embeddings)
- Alembic migrations

## Install

```bash
pip install orvin
```

Focused install surfaces are exposed as extras where they actually add dependencies:

```bash
pip install "orvin[v2]"
pip install "orvin[dev]"
```

For local repo testing before PyPI publish:

```bash
pip install .
pip install ".[v2]"
```

You can also run the operator surfaces with module entrypoints:

```bash
python -m orvin.cli --help
python -m orvin.mcp_server --help
```

## Run

```bash
alembic upgrade head
uvicorn orvin.main:app --reload --app-dir src
```

For local Redis:

```bash
redis-server --daemonize yes --port 6379 --save '' --appendonly no --dir /tmp
```

For local-only development without auth, explicitly opt in:

```bash
$env:ORVIN_ALLOW_UNAUTHENTICATED='true'
```

For any shared or internet-facing deployment, configure `ORVIN_API_KEYS`.

## Local stack with Docker

Copy `.env.example` to `.env`, then run:

```bash
docker compose up --build
```

This starts:

- pgvector-enabled Postgres
- Redis
- the FastAPI API service
- the outbox worker

The API will be reachable at `http://localhost:8000`, and `GET /v1/meta` exposes runtime, auth, and SDK surface metadata for tooling.

For the standalone test dashboard:

```bash
cd dashboard
npm install
npm run dev
```

## Current status

This implementation includes:

- API scaffold
- first-party CLI commands for runtime, inspection, ingest, and seeding
- MCP stdio server with workspace-scoped read tools, resources, and opt-in ingest tools
- request/response schemas
- domain models
- Postgres repository
- SQLAlchemy models for the Postgres path
- Alembic migrations for interaction runtime fields, outbox retries, and idempotency
- local embedding pipeline via FastEmbed
- hybrid `pgvector + full-text` search
- Redis-backed session/context cache
- thin hot-path ingest with transactional writes and idempotency keys
- outbox-driven async jobs for memory extraction, embedding, episode creation, commitment reconciliation, and interaction consolidation
- durable-memory lifecycle handling for hypothesis promotion, supersession, repeated evidence, and tool-linked commitments
- evidence-aware context/search responses with confidence and retrieval explanations
- channel-aware retrieval policy, reactive-retrieval gating, and search caching
- debugger endpoints for memory evidence, audit trails, hot-state recovery, and runtime metrics
- issue extraction, repair history, acoustic hint memory, stale-commitment surfacing, and stronger episode summaries
- structured memory-intelligence pipeline with multilingual extraction, evidence spans, confidence calibration, interaction-level turn bundles, and optional model-backed extraction plus verification
- versioned memory history, contradiction relationships, participant event feeds, structured profile synthesis, and export/import/privacy tooling
- workspace write quota enforcement for high-volume ingest and batch import paths
- replay fixtures plus eval-oriented extraction tests and fixture-driven quality checks
- managed API key generation, revocation, and admin endpoints for distribution testing
- standalone Next.js operator dashboard for API keys, SDK snippets, MCP setup, connectors, documents, participants, and ingest playgrounds

Configuration is loaded from `.env`. Use `.env.example` as the baseline and point `ORVIN_DATABASE_URL` at your own Postgres instance or Neon branch.

## Security

- All non-health API routes require an API key unless `ORVIN_ALLOW_UNAUTHENTICATED=true` is explicitly set.
- API keys are accepted via `Authorization: Bearer <key>` or `X-API-Key: <key>`.
- `ORVIN_API_KEYS` remains the bootstrap/admin key path.
- Managed keys created through `/v1/admin/api-keys` are stored by the platform and can be revoked independently.
- `/v1/health` and `/v1/health/ready` are readiness checks.
- `/v1/health/live` is a lightweight liveness check.

## Fingerprinting

Every response includes:

- `X-Orvin-Fingerprint`
- `X-Orvin-License`
- `X-Orvin-Edition`
- `X-Orvin-Version`

This gives upstream AGPL builds an identifiable release fingerprint.

## CLI and MCP

The repo now ships two operator-facing entrypoints:

- `orvin` for CLI operations such as `health`, `context get`, `search`, `serve-api`, and `serve-worker`
- `orvin keys` for managed API key list/create/revoke flows
- `orvin-mcp` for a stdio MCP server that wraps the same canonical API and local service layer
- `orvin.OrvinClient` as the first-party Python SDK surface
- `sdks/typescript` as the first-party TypeScript SDK package
- `dashboard` as the standalone testing UI

Remote MCP mode requires `ORVIN_BASE_URL` plus an API key. Local MCP mode is opt-in via `--local` or `ORVIN_MCP_LOCAL_MODE=true`.

Examples:

```bash
orvin health
orvin-mcp --local
orvin-mcp --base-url https://orvin.example --api-key $env:ORVIN_API_KEYS
```

By default the MCP server exposes only safe read tools and resources. Enable debug tools with `--enable-debug-tools` and enable mutating ingest tools with `--enable-write-tools`.

## Examples

First-party examples live in [`examples/README.md`](examples/README.md).

SDK source now lives in:

- `src/orvin/client.py` for Python
- `sdks/typescript` for TypeScript

The TypeScript SDK is packaged as `@orvin/sdk`:

```bash
npm install @orvin/sdk
```

The main Track 8 examples are:

- adapter flows for LiveKit, Pipecat, browser, Deepgram, Vapi, Retell, and ElevenLabs runtimes
- CLI operator workflows in [`examples/cli_workflow.md`](examples/cli_workflow.md)
- stdio MCP client flow in [`examples/mcp_stdio_example.py`](examples/mcp_stdio_example.py)
- document ingestion flow in [`examples/document_ingestion_example.py`](examples/document_ingestion_example.py)
- the direct dashboard app in [`dashboard/README.md`](dashboard/README.md)

## Test

```bash
$env:PYTHONPATH='src'; pytest -q
```

## License

This project is licensed under `AGPL-3.0-only`. If you modify and run this server software for users over a network, the AGPL requires you to provide the corresponding source for that modified server program.
