Provenkin

Evidence-first genealogical AI research platform. Provenkin is not a family tree application — it is a research engine that traces every conclusion back to supporting sources, models uncertainty explicitly, and is built to handle the complexity of real historical evidence.

Built on CrewAI, Provenkin orchestrates multiple AI agents (interviewer, researcher, verifier, report writer) into a structured research pipeline. It is designed for genealogists, historians, and anyone conducting evidence-based investigation of people and relationships across time.

Key Features

• Evidence-first architecture — every conclusion is linked to its supporting sources
• Confidence modeling — explicit, non-binary confidence values for assertions
• Interview agent — adaptive questioning to capture known facts and identify research goals
• Multi-source research — web search, census, newspapers, FamilySearch, FindAGrave, National Archives, and more
• Verification pipeline — cross-references evidence, resolves conflicts, assigns confidence scores
• Capability plugin system — providers and plugins auto-discovered, no core code changes needed
• Historical domain model v2 — represents historical reality without assuming nuclear families, western naming conventions, binary confidence, or static identities
• Multi-format reporting — Markdown and PDF report generation with tone guides

Architecture Overview

provenkin/
├── config/          # Environment loading, settings, LLM factory, logging
├── models/          # Domain entities (Person, Evidence, Source, Event, ...)
│   └── domain/      # V2 historical reality model (Identity, Assertion, ...)
├── agents/          # CrewAI agents, each with a single responsibility
├── crews/           # Crew compositions that orchestrate groups of agents
├── services/        # Use-case orchestrators (interview, research, verify, report)
├── tools/           # External data source integrations
├── capabilities/    # Plugin framework with auto-discovery
├── providers/       # Built-in capability implementations
├── memory/          # Session and case-level storage
├── database/        # Persistence layer (repository pattern, SQLite)
├── tests/           # Test suite
└── docs/            # Architecture and design documentation

See docs/ARCHITECTURE.md for a detailed walkthrough.

Requirements

• Python 3.10+
• A running LLM endpoint (any OpenAI-compatible API — see Configuration below)

Installation

# 1. Clone the repository
git clone https://github.com/2lost2bfound/provenkin.git
cd provenkin

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate     # Windows

# 3. Install dependencies — choose one:
pip install -e .            # Option A: install as package (recommended)
pip install -r requirements.txt  # Option B: install dependencies only
# Option C: set PYTHONPATH instead of installing:
#   export PYTHONPATH=$PWD

# 4. Configure environment
cp .env.example .env
# Edit .env with your LLM endpoint credentials

Quickstart

from services.orchestration_service import CaseOrchestrator

orchestrator = CaseOrchestrator()
case = orchestrator.create_case(
    title="Smith Family Research",
    research_goal="Find the birth record of John Smith, born ~1890 in Ohio",
)
case = orchestrator.resume(case)
print(f"Pipeline complete: {case.status}")

Or from the command line:

python main.py

Configuration

All configuration is via environment variables in .env:

Variable	Required	Description
OMNIRouter_API_KEY	Yes	API key for your LLM endpoint
OMNIRouter_BASE_URL	Yes	Base URL (e.g. http://localhost:20128/v1, https://api.openai.com/v1)
OMNIRouter_MODEL	Yes	Model identifier (e.g. openai/gpt-4o, ds-web/deepseek-v4-pro)
RESEND_API_KEY	No	For the email agent
NARA_API_KEY	Yes	National Archives catalog API key

Provenkin works with any OpenAI-compatible API — OmniRouter, OpenAI, OpenRouter, Anthropic (via proxy), or a local model server. Only the three OMNIRouter_* variables need changing to switch providers.

Testing

pytest tests/ -v

Project Structure

provenkin/
├── config/            # Settings, LLM factory, logging
├── models/            # Domain models (Pydantic)
│   └── domain/        # V2 historical reality model
├── agents/            # AI agents (strategy pattern)
├── crews/             # Agent orchestration
├── services/          # Business logic orchestrators
├── tools/             # External data source wrappers
├── capabilities/      # Plugin system
├── providers/         # Built-in capabilities
├── memory/            # Session and case storage
├── database/          # SQLite persistence
├── templates/         # Report tone guides
├── tests/             # Test suite
└── docs/              # Documentation

Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR workflow.

License

PolyForm Noncommercial License 1.0.0 — see LICENSE for details.

Commercial use requires a separate paid license. See COMMERCIAL.md for inquiries.