Quick Start

Get TruthKeeper up and running in your project in just a few steps.

Prerequisites

  • Python 3.11 or higher
  • pip or uv package manager
  • (Optional) PostgreSQL 15+ with pgvector for production use

Installation

Using pip

pip install truthkeeper

Using uv (recommended)

uv add truthkeeper

From source

git clone https://github.com/SimplyLiz/truthkeeper.git
cd truthkeeper
pip install -e .

Configuration

Create a .env file in your project root:

# Database (SQLite for development)
DATABASE_URL=sqlite:///./truthkeeper.db

# Or PostgreSQL for production
# DATABASE_URL=postgresql://user:pass@localhost:5432/truthkeeper

# API Configuration
TRUTHKEEPER_HOST=0.0.0.0
TRUTHKEEPER_PORT=8000

# Verification (optional)
OPENAI_API_KEY=sk-...  # For MiniCheck verification

Start the Server

Using the CLI

truthkeeper serve

Using Docker

docker run -p 8000:8000 \
  -e DATABASE_URL=sqlite:///./data/truthkeeper.db \
  -v $(pwd)/data:/app/data \
  ghcr.io/simplyliz/truthkeeper:latest

Create Your First Claim

Using the API

curl -X POST http://localhost:8000/api/v1/claims \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The UserService class handles authentication",
    "evidence": [
      {
        "source": "file://src/services/user.py",
        "type": "CODE",
        "excerpt": "class UserService:\n    def authenticate(self, username, password):"
      }
    ],
    "dependencies": [
      {
        "target": "file://src/services/user.py",
        "type": "HARD"
      }
    ]
  }'

Using the Python SDK

from truthkeeper import TruthKeeperClient, Evidence, Dependency

client = TruthKeeperClient("http://localhost:8000")

# Create a claim
claim = await client.create_claim(
    content="The UserService class handles authentication",
    evidence=[
        Evidence(
            source="file://src/services/user.py",
            type="CODE",
            excerpt="class UserService:\n    def authenticate(self, username, password):"
        )
    ],
    dependencies=[
        Dependency(
            target="file://src/services/user.py",
            type="HARD"
        )
    ]
)

print(f"Created claim: {claim.id}")
print(f"State: {claim.state}")
print(f"Confidence: {claim.confidence}")

Query Claims

# Search for relevant claims
claims = await client.search_claims(
    query="authentication",
    min_confidence=0.8,
    states=["SUPPORTED"]
)

for claim in claims:
    print(f"{claim.content} (confidence: {claim.confidence})")

Register a Source Watcher

Source watchers monitor external sources and trigger staleness checks when they change:

from truthkeeper import FileSourceWatcher

# Watch local files for changes
watcher = FileSourceWatcher(
    client=client,
    paths=["src/"],
    patterns=["**/*.py"]
)

# Start watching (runs in background)
await watcher.start()

# When a file changes, dependent claims are automatically marked STALE

Handle Stale Claims

# Get claims that need reverification
stale_claims = await client.get_stale_claims()

for claim in stale_claims:
    print(f"Stale: {claim.content}")

    # Trigger reverification
    result = await client.reverify_claim(claim.id)

    if result.new_state == "OUTDATED":
        print(f"  -> Claim is now outdated")
    elif result.new_state == "SUPPORTED":
        print(f"  -> Claim still valid (confidence: {result.confidence})")

Next Steps