truthgit 0.5.2

Version control for verified truth

TruthGit

Version control for verified truth.

Website • Documentation • Discord

---

Like Git tracks code, TruthGit tracks claims. Verify with AI consensus. Store immutably. Trust, but verify.

$ truthgit init
$ truthgit claim "Water boils at 100°C at sea level" --domain physics
$ truthgit verify

[OLLAMA:HERMES3] 95% - Accurate under standard atmospheric pressure
[OLLAMA:NEMOTRON] 94% - True at 1 atm, varies with altitude

✓ PASSED  Consensus: 95%
Verification: a7f3b2c1

What makes TruthGit different?

TruthGit doesn't just count votes—it understands the nature of disagreement:

$ truthgit claim "Free will exists" --domain philosophy
$ truthgit verify

[OLLAMA:HERMES3] 30% - Contested philosophical question
[OLLAMA:NEMOTRON] 30% - Determinism vs libertarianism debate

⚡ UNRESOLVABLE  Type: MYSTERY
Preserved positions: 2

# Not a failure—preserved as legitimate philosophical disagreement

Why TruthGit?

TruthGit is safety infrastructure for autonomous AI agents.

When an AI agent is about to take a high-stakes action (trading, deployment, decision-making), it needs to verify its assumptions first. TruthGit provides the verification layer:

Agent wants to act on claim → TruthGit verifies → PASSED/MYSTERY/GAP
                                                      ↓
                                           PASSED: Agent acts
                                           MYSTERY: Agent aborts (uncertainty)
                                           GAP: Escalate to human

Core Capabilities

• Ontological consensus — Understands what type of disagreement, not just how much
• Safety-first — MYSTERY claims prevent agents from acting on uncertainty
• Multi-validator consensus — No single AI is trusted alone
• Fallacy detection — Identifies logical errors in validator reasoning
• Auditable history — Every decision is traceable to verified claims
• Local-first — Works offline with Ollama, no API keys required
• Open protocol — Self-host, federate, integrate

Use Case: Trading Agents

# Before placing a trade, verify the analysis
claims = ["Market sentiment is bullish", "Volume supports breakout"]

for claim in claims:
    result = truthgit.verify(claim)
    if result.status == "MYSTERY":
        return "Abort: uncertainty too high for real money"
    if result.status == "GAP":
        await escalate_to_human(claim)

# Only execute if all claims pass
execute_trade()

Ontological Consensus (v0.5.0)

Most verification systems ask: "How much agreement?" TruthGit asks: "What type of disagreement?"

The Three Types

Type	Symbol	Meaning	Action
PASSED	✓	Validators agree above threshold	Claim verified
LOGICAL_ERROR	✗	One validator has a bug/fallacy	Exclude outlier, recalculate
MYSTERY	⚡	Legitimate unknowable (philosophy)	Preserve all positions as data
GAP	⏳	Unfalsifiable claim	Escalate to human mediation

Why This Matters

Traditional: 60% consensus on "Free will exists" → FAILED ❌
TruthGit:    60% consensus on "Free will exists" → MYSTERY ⚡ (preserved)

Validators agreeing on uncertainty doesn't resolve underlying unknowability. A contested philosophical claim with high agreement is still a MYSTERY—and that's valuable information, not a failure.

Domain-Aware Processing

For philosophical domains (philosophy, ethics, religion, metaphysics, epistemology), TruthGit analyzes the claim's nature first:

from truthgit.ontological_classifier import calculate_ontological_consensus

results = {
    "CLAUDE": (0.70, "Free will emerges from complexity"),
    "GPT": (0.30, "Determinism is more parsimonious"),
    "GEMINI": (0.50, "The question may be malformed"),
}

consensus = calculate_ontological_consensus(
    claim="Free will exists",
    validator_results=results,
    domain="philosophy"
)

print(consensus.status)           # ConsensusStatus.UNRESOLVABLE
print(consensus.disagreement_type) # DisagreementType.MYSTERY
print(consensus.preserved_positions)  # All 3 reasonings preserved

Fallacy Detection

TruthGit detects logical fallacies in validator reasoning:

from truthgit.fallacy_detector import detect_fallacies

result = detect_fallacies("He's an idiot, so his argument is wrong.")
print(result.valid)      # False
print(result.fallacies)  # [Fallacy(type='AD_HOMINEM', ...)]

Detected fallacies (11 types):

Formal	Informal
Affirming the Consequent	Ad Hominem
Denying the Antecedent	Straw Man
False Dilemma	Appeal to Authority
Circular Reasoning	Slippery Slope
	Appeal to Emotion
	Hasty Generalization
	Red Herring

When a validator's reasoning contains fallacies, TruthGit classifies the disagreement as LOGICAL_ERROR and can exclude the outlier.

Hypothesis Testing

TruthGit evaluates claims for falsifiability:

from truthgit.hypothesis_tester import evaluate_hypothesis, EpistemicStatus

result = evaluate_hypothesis("Everything happens for a reason")
print(result.status)      # EpistemicStatus.UNFALSIFIABLE
print(result.falsifiable) # False

result = evaluate_hypothesis("Evolution explains biodiversity")
print(result.status)      # EpistemicStatus.ESTABLISHED
print(result.falsifiable) # True

Epistemic statuses:

• ESTABLISHED — Scientific consensus exists
• CONTESTED — Active academic debate
• SPECULATIVE — Insufficient evidence
• FRINGE — Contradicts established science
• UNFALSIFIABLE — Cannot be tested

Installation

# Install TruthGit
pip install truthgit

# For local validation (recommended)
pip install truthgit[local]

# For cloud APIs (optional)
pip install truthgit[cloud]

# Everything
pip install truthgit[all]

Cloud Deployment

TruthGit API is deployed on Google Cloud Run for production use.

Production API

Base URL: https://truthgit-api-342668283383.us-central1.run.app

Endpoints:

Endpoint	Method	Description
/api/status	GET	Repository status
/api/verify	POST	Verify a claim
/api/prove	POST	Generate proof certificate
/api/verify-proof	POST	Verify a certificate
/api/search	GET	Search verified claims

Example:

curl -X POST https://truthgit-api-342668283383.us-central1.run.app/api/verify \
  -H "Content-Type: application/json" \
  -d '{"claim": "Water boils at 100°C at sea level", "domain": "physics"}'

Deploy Your Own

# Clone the repository
git clone https://github.com/lumensyntax/truthgit
cd truthgit

# Deploy to Cloud Run
gcloud run deploy truthgit-api \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --port 8080 \
  --memory 1Gi \
  --timeout 300

# Configure API keys for multi-validator consensus
gcloud run services update truthgit-api \
  --region us-central1 \
  --set-env-vars "ANTHROPIC_API_KEY=sk-ant-...,OPENAI_API_KEY=sk-...,GOOGLE_API_KEY=..."

---

Local Setup (No API Keys)

TruthGit works locally with Ollama:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull models for diverse validation
ollama pull llama3
ollama pull mistral
ollama pull phi3

# Verify setup
truthgit validators --local

Quick Start

# Initialize a truth repository
truthgit init

# Create claims to verify
truthgit claim "The Earth orbits the Sun" --domain astronomy
truthgit claim "Python was created by Guido van Rossum" --domain programming

# Verify with local AI consensus
truthgit verify --local

# View verification history
truthgit log

Commands

Command	Description
truthgit init	Initialize a new truth repository
truthgit claim "..." --domain x	Create a claim to verify
truthgit verify [--local]	Verify with ontological consensus
truthgit verify --simple	Verify with simple threshold only
truthgit status	Show repository status
truthgit log	Show verification history
truthgit cat <hash>	Show object details
truthgit validators	Show available validators

Verification Modes

# Default: Ontological consensus (understands disagreement types)
truthgit verify --local

# Simple: Threshold-only (legacy behavior)
truthgit verify --local --simple

GitHub Actions

Verify your documentation claims automatically on every push:

# .github/workflows/truthgit.yml
name: TruthGit Verify

on:
  push:
    paths: ['docs/**', '*.md']
  pull_request:
    paths: ['docs/**', '*.md']

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lumensyntax-org/truthgit/.github/actions/verify@main
        with:
          path: 'docs/'
          fail-on-unverified: 'false'

Action Inputs

Input	Default	Description
path	docs/	Path to documentation files
min-verification-rate	0	Minimum rate required (0-100). Fails if below.
comment-on-pr	false	Post verification summary as PR comment
generate-report	true	Upload verification report artifact
python-version	3.11	Python version to use
github-token	${{ github.token }}	Token for PR comments

Action Outputs

Output	Description
total-claims	Total claims found
verified-claims	Verified claims count
unverified-claims	Unverified claims count
verification-rate	Verification percentage
passed	Whether verification passed all thresholds

Example: PR Comments with Threshold

- uses: lumensyntax-org/truthgit/.github/actions/verify@main
  with:
    path: 'docs/'
    min-verification-rate: '80'
    comment-on-pr: 'true'

This posts a comment like:

✅ TruthGit Verification Passed

Metric	Value
Total Claims	24
Verified	22
Unverified	2
Verification Rate	91.6%
Required Rate	80%

How It Works

1. Content-Addressable Storage

Every object is stored by its SHA-256 hash (like Git):

.truth/
├── objects/
│   ├── cl/  # Claims
│   ├── ax/  # Axioms (immutable truths)
│   ├── ct/  # Contexts (groups of claims)
│   └── vf/  # Verifications (snapshots)
├── refs/
│   ├── consensus/  # Verified truth
│   └── perspectives/  # Per-validator views
└── HEAD

2. Ontological Consensus

Claims are verified by multiple independent validators, then classified by disagreement type:

        ┌─────────────┐
        │   Claim     │
        │  + Domain   │
        └──────┬──────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌───────┐  ┌───────┐  ┌───────┐
│Hermes │  │Nemotron│ │ Phi3  │
│  92%  │  │  88%   │ │  90%  │
└───────┘  └───────┘  └───────┘
               │
               ▼
     ┌─────────────────┐
     │ Ontological     │
     │ Classification  │
     └────────┬────────┘
              │
    ┌─────────┼─────────┐
    ▼         ▼         ▼
 PASSED    MYSTERY     GAP
   ✓          ⚡         ⏳
 (verify)  (preserve) (mediate)

Flow:

1. Analyze claim's epistemic nature (falsifiable? contested?)
2. For philosophy domains: claim nature determines handling
3. For science domains: variance triggers fallacy detection
4. Classify disagreement → take appropriate action

Default threshold: 66% (configurable)

3. Verification as Commit

Like Git commits, verifications are immutable snapshots:

from truthgit import TruthRepository

repo = TruthRepository()
repo.init()

# Create claim
claim = repo.claim(
    content="E=mc²",
    domain="physics",
    confidence=0.9,
)

# Verify with multiple validators (ontological by default)
verification = repo.verify(
    verifier_results={
        "HERMES3": (0.95, "Mass-energy equivalence confirmed"),
        "NEMOTRON": (0.92, "Einstein's famous equation"),
        "PHI3": (0.94, "Verified E=mc² relationship"),
    },
    claim_content="E=mc²",
    claim_domain="physics",
)

print(f"Consensus: {verification.consensus.value:.0%}")
# Consensus: 94%

# Access ontological analysis
if verification.ontological_consensus:
    onto = verification.ontological_consensus
    print(f"Status: {onto.status}")           # PASSED
    print(f"Type: {onto.disagreement_type}")  # None (no disagreement)

Handling Philosophy Claims

# Philosophy claims are handled differently
claim = repo.claim(
    content="Consciousness is fundamental to reality",
    domain="philosophy",
    confidence=0.5,
)

verification = repo.verify(
    verifier_results={
        "CLAUDE": (0.60, "Panpsychism has merit"),
        "GPT": (0.40, "Emergentism is simpler"),
    },
    claim_content="Consciousness is fundamental to reality",
    claim_domain="philosophy",
)

onto = verification.ontological_consensus
print(onto.status)              # UNRESOLVABLE
print(onto.disagreement_type)   # MYSTERY
print(onto.preserved_positions) # Both reasonings preserved

Validators

TruthGit supports pluggable validators:

Local (No API Keys)

from truthgit.validators import OllamaValidator

validators = [
    OllamaValidator("llama3"),
    OllamaValidator("mistral"),
    OllamaValidator("phi3"),
]

Cloud (Optional)

from truthgit.validators import ClaudeValidator, GPTValidator, GeminiValidator

# Set environment variables:
# ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY

validators = [
    ClaudeValidator(),
    GPTValidator(),
    GeminiValidator(),
]

Human

from truthgit.validators import HumanValidator

validators = [
    OllamaValidator("llama3"),
    HumanValidator("reviewer"),  # Interactive CLI prompt
]

Configuration

.truth/config:

{
  "version": "1.0.0",
  "consensus_threshold": 0.66,
  "default_verifiers": ["OLLAMA:LLAMA3", "OLLAMA:MISTRAL"]
}

Use Cases

• Knowledge Bases — Build verified, auditable knowledge graphs
• Fact Checking — Multi-source verification for claims
• Research — Track hypotheses and their verification status
• AI Training Data — Curate high-quality, verified datasets
• Documentation — Version control for technical claims

Roadmap

Completed in v0.5.0:

• Ontological consensus — Classify disagreement types
• Fallacy detection — 11 logical fallacy patterns
• Hypothesis testing — Falsifiability evaluation
• Philosophy domain support — MYSTERY/GAP handling

Upcoming:

• truthgit mediate — Human mediation workflow for GAP claims
• Federation — Sync truth between repositories
• IPFS Storage — Decentralized content storage
• Web UI — Visual truth explorer
• GitHub Integration — Verify claims in issues/PRs
• VS Code Extension — Inline claim verification

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/truthgit/truthgit
cd truthgit
pip install -e ".[dev]"
pytest

API Reference

Core Modules

# Ontological consensus
from truthgit.ontological_classifier import (
    calculate_ontological_consensus,
    classify_disagreement,
    DisagreementType,      # LOGICAL_ERROR, MYSTERY, GAP
    ConsensusStatus,       # PASSED, FAILED, UNRESOLVABLE, PENDING_MEDIATION
    OntologicalConsensus,
)

# Fallacy detection
from truthgit.fallacy_detector import (
    detect_fallacies,
    FallacyCategory,  # FORMAL, INFORMAL
    FallacyResult,
    Fallacy,
)

# Hypothesis testing
from truthgit.hypothesis_tester import (
    evaluate_hypothesis,
    EpistemicStatus,  # ESTABLISHED, CONTESTED, SPECULATIVE, FRINGE, UNFALSIFIABLE
    HypothesisType,   # EMPIRICAL, EXISTENTIAL, UNIVERSAL, CAUSAL, MATHEMATICAL
    HypothesisResult,
)

# Repository operations
from truthgit import TruthRepository, Claim, Axiom, Verification

OntologicalConsensus Object

@dataclass
class OntologicalConsensus:
    status: ConsensusStatus           # PASSED, FAILED, UNRESOLVABLE, PENDING_MEDIATION
    value: float                      # Mean confidence (0.0-1.0)
    threshold: float                  # Consensus threshold (default 0.66)
    disagreement_type: DisagreementType | None  # LOGICAL_ERROR, MYSTERY, GAP
    preserved_positions: dict | None  # For MYSTERY: all validator reasonings
    mediation_context: str | None     # For GAP: brief for human mediator
    excluded_validators: list | None  # For LOGICAL_ERROR: which were excluded
    validator_details: dict           # Original validator results

MCP Server (Model Context Protocol)

TruthGit includes an MCP server for integration with Claude Desktop and other MCP clients.

Purpose

Production safety infrastructure for autonomous AI agents.

Unlike lumensyntax-mcp (lightweight, local) or @lumensyntax/mcp-server (development tools), the TruthGit MCP is designed for high-stakes production environments where agents need verified truth before acting.

Installation

pip install truthgit

Configuration

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "truthgit": {
      "command": "python",
      "args": ["-m", "truthgit.mcp_server"]
    }
  }
}

Tools

Tool	Description
truthgit_verify_claim	Multi-validator AI consensus verification
truthgit_prove	Generate cryptographic proof certificate
truthgit_verify_proof	Verify proof without access to repository
truthgit_search	Search verified claims in repository
truthgit_status	Show repository status

Use Case: Agent Safety Gates

# Before autonomous action
result = mcp.truthgit_verify_claim("ETH price is above $3000", domain="market")

match result.classification:
    case "PASSED":
        execute_trade()      # Verified - proceed
    case "MYSTERY":
        abort()              # Unknowable - don't risk
    case "GAP":
        escalate_to_human()  # Needs human judgment

Related MCPs

MCP	Purpose	Use When
lumensyntax-mcp	Lightweight local verification	End-user fact-checking
@lumensyntax/mcp-server	Development & research	Building new features
TruthGit MCP	Production safety gates	Autonomous agent decisions

---

Philosophy

"In a world where AI can generate infinite content, the scarce resource is verified truth."

TruthGit is built on four principles:

1. Ontology over counting — Ask "what type?" before "how much?"
2. Consensus over authority — No single source is trusted
3. Immutability over mutation — Truth is append-only
4. Openness over control — Protocol is open, self-hosting is encouraged

The Ontological Insight

Traditional verification systems treat all disagreement the same: if validators don't agree, the claim fails. But not all disagreement is equal:

• When a validator makes a logical error, exclude it and recalculate
• When the claim is genuinely unknowable, preserve the disagreement as data
• When the claim is unfalsifiable, escalate to human judgment

This is the philosophical core that makes TruthGit different from simple voting systems.

License

MIT © TruthGit

---

truthgit.com — Version control for verified truth.