Metadata-Version: 2.4
Name: veritas-epistemic
Version: 0.2.0
Summary: Epistemic confidence engine — every AI belief carries its provenance
Project-URL: Repository, https://github.com/AILIFE1/veritas
Project-URL: Homepage, https://cathedral-ai.com
License: MIT License
        
        Copyright (c) 2026 Mike Ward
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,belief,confidence,epistemics,knowledge,llm,provenance,reasoning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: sentence-transformers>=2.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.0; extra == 'semantic'
Description-Content-Type: text/markdown

# Veritas

[![Tests](https://github.com/AILIFE1/veritas/actions/workflows/ci.yml/badge.svg)](https://github.com/AILIFE1/veritas/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/veritas-epistemic.svg)](https://pypi.org/project/veritas-epistemic/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Epistemic confidence engine — beliefs with provenance.**

Most knowledge systems store facts. Veritas stores *how well you know them*.

Every claim carries a confidence vector derived from its sources, how those sources have aged, whether its foundations are solid, and whether contradicting evidence exists in the database. Shake a foundation and everything built on it moves automatically.

---

## The problem

AI agents act on beliefs they can't evaluate. "The API is reliable" — based on what? One observation from 2022? Twenty independent tests from this month? A single fragile assumption that everything else depends on?

Without epistemic structure, agents overclaim certainty or collapse into paralysis. Veritas gives beliefs a shape: not just a value, but fragility, staleness, and a provenance chain you can audit.

---

## Install

```bash
pip install veritas-epistemic
# For semantic contradiction detection:
pip install veritas-epistemic[semantic]
```

---

## Quick start

```bash
# Add a claim with sources
veritas add "Persistent memory improves agent consistency" \
  --source "Cathedral benchmark 2026 — 10.8x stability improvement" --weight 0.85 \
  --source "Empirical session tests 2026" --weight 0.75 \
  --context cathedral

# See full provenance breakdown
veritas trace "Persistent memory"

# Run the reasoning guard before acting
veritas check "Persistent memory improves agent consistency"
```

```
  Claim : Persistent memory improves agent consistency
Context : cathedral
     ID : dac6295c  (added 2026-05-08)

  Direct   [##################..] 0.90  src:2  contra:0  fragility:0.12
```

---

## Core concepts

### Confidence vectors

Confidence is not a single number — it has a shape.

| Field | Meaning |
|---|---|
| `value` | Current best estimate (0–1), with temporal decay applied |
| `fragility` | How much confidence drops if the best source is removed |
| `staleness_penalty` | How much evidence aging has already cost |
| `source_diversity` | How independent your sources are from each other |

```python
from veritas import VeritasDB, calculate_confidence
from veritas.models import Claim, Source, Stance

db = VeritasDB("~/.veritas/veritas.db")
claim = db.search("persistent memory")[0]
cv = calculate_confidence(claim.sources)

print(cv.value)            # 0.90
print(cv.fragility)        # 0.12  — reasonably robust
print(cv.staleness_penalty) # 0.00  — sources are fresh
```

---

### Temporal decay

Evidence ages. A 1986 study should carry less weight than a 2024 replication. A theorem from 1936 should carry exactly the same weight as the day it was proved.

| Source type | Half-life | Example |
|---|---|---|
| `MATHEMATICAL` | timeless | Turing 1936, Gödel 1931 |
| `THEORETICAL` | ~140 years | Newton, Darwin |
| `EMPIRICAL` | ~10 years | Studies, benchmarks |
| `AUTHORITY` | ~6 years | Expert consensus |
| `META` | ~4 years | Literature reviews |
| `ANECDOTAL` | ~2 years | Personal accounts |

```bash
# See what's going stale
veritas stale

  Claims losing confidence to age:

  -0.32  [##########..........] 0.54  Minsky 1967: AI will solve all problems
         59.0y  0.70->0.07  [ANEC]  Minsky 1967 interview

# Attach a date to a source so decay starts from publication, not today
veritas source "neural networks can learn" \
  --citation "Hinton 1986 backpropagation" --weight 0.85 --date 1986-01-01
```

---

### Belief propagation

Claims depend on other claims. When a foundation weakens, everything built on it updates automatically.

```bash
veritas add "AI agents currently lose state between sessions" \
  --source "OpenAI API docs — no persistent memory" --weight 0.95

veritas add "Developers need persistent agent memory" \
  --source "Community feedback 2026" --weight 0.65

veritas add "Cathedral will find a market" \
  --source "Personal assessment" --weight 0.60

# Wire the dependency chain
veritas depends "Developers need persistent" --on "AI agents currently lose state"
veritas depends "Cathedral will find a market" --on "Developers need persistent"

veritas chain "Cathedral will find a market"
```

```
  [0.86] Cathedral will find a market
    |-- [IND] -->
      [0.89] Developers need persistent agent memory
        |-- [IND] -->
          [0.95] AI agents currently lose state between sessions
```

Now add a contradicting source to the bottom claim and watch it propagate upward — without touching the top two claims.

---

### Semantic contradiction detection

Finds conflicts across different vocabulary. No shared words needed.

```python
from veritas import VeritasDB, find_contradictions
from veritas.models import Claim, Source, Stance

db = VeritasDB("~/.veritas/veritas.db")
claim = db.search("physical activity strengthens cardiovascular")[0]

contras = find_contradictions(claim, db.all_claims(), db=db)
# Finds: "Exercise has no proven benefit for heart health"
# — zero content words in common, caught via sentence embeddings
```

Falls back to keyword matching if `sentence-transformers` is not installed.

---

### Reasoning guard

Before an agent acts on a belief, check whether it actually holds up.

```python
from veritas import VeritasDB, ReasoningGuard

db = VeritasDB("~/.veritas/veritas.db")
guard = ReasoningGuard(db)

result = guard.check("GPT-3 represents the state of the art in language models")
print(result)
```

```
[CAUTION] confidence=0.87  Belief has weaknesses that should be acknowledged
  * Stale — evidence aging has reduced confidence by 0.12
```

```python
if result.should_proceed:
    # act
else:
    # surface the flags to the user or upstream system
    for flag in result.flags:
        print(flag)
```

Verdicts: `PROCEED` · `CAUTION` · `HALT`

Triggers: low confidence · single source · high fragility · staleness · contradictions

#### Threshold reference

| Condition | Default threshold | Verdict effect |
|---|---|---|
| `confidence < 0.30` | HALT_CONFIDENCE | **HALT** — don't act |
| `confidence < 0.55` | CAUTION_CONFIDENCE | **CAUTION** — flag uncertainty |
| `source_count == 1` | — | **CAUTION** — always, regardless of confidence |
| `fragility > 0.25` | FRAGILITY_CAUTION | **CAUTION** — drops badly if best source removed |
| `staleness_penalty > 0.08` | STALENESS_CAUTION | **CAUTION** — evidence aging has cost confidence |
| contradiction `confidence >= 0.45` | CONTRA_HALT_CONF | **CAUTION** — well-sourced counter-claim exists |

All thresholds are constants at the top of `veritas/guard.py` — tune them per use case.

---

### Epistemic fingerprint

Every belief system has a characteristic reasoning style. The fingerprint measures it.

```bash
veritas fingerprint --context cathedral
```

```
  Epistemic Fingerprint: cathedral
  ========================================================
  Claims: 12   Sources: 31   Avg sources/claim: 2.6

  Source composition:
    EMPIRICAL      [################........] 65%
    AUTHORITY      [########................] 32%
    ANECDOTAL      [##......................] 8%

  Confidence profile:
    Average        [##################......] 0.87
    Fragility      [####....................] 0.18
    Overconfident  [##......................] 8% of claims
    Single-source  [######..................] 25% of claims

  Epistemic health:
    Contradicted   [####....................] 17% of claims
    Rigor score    [################........] 0.68
    Calibration    [####################....] 0.84
    Overall        [##################......] 0.76
```

Compare two contexts side by side:

```bash
veritas compare cathedral philosophy
```

Two agents with the same beliefs but different fingerprints are different kinds of reasoners.

---

## Full command reference

```
veritas add         STATEMENT [--source ...] [--weight] [--date YYYY-MM-DD] [--context]
veritas source      CLAIM_REF --citation ... [--weight] [--stance] [--date]
veritas depends     CLAIM_REF --on CLAIM_REF [--inference DEDUCTIVE|INDUCTIVE|ABDUCTIVE]
veritas trace       CLAIM_REF          full provenance breakdown
veritas chain       CLAIM_REF          dependency tree with live confidence at each level
veritas check       CLAIM_TEXT         reasoning guard verdict
veritas challenge   CLAIM_REF          find contradicting claims
veritas fingerprint [--context]        epistemic style of a belief system
veritas compare     CONTEXT_A CONTEXT_B  side-by-side fingerprint diff
veritas query       [--fragile] [--low] [--unsourced] [--context]
veritas weakest     [--limit]          most fragile beliefs
veritas stale       [--threshold]      claims losing confidence to age
veritas report                         overall epistemic health
veritas demo                           live walkthrough of all capabilities
veritas delete      CLAIM_REF
```

---

## Python API

```python
from veritas import (
    VeritasDB,
    Claim, Source, Stance, SourceType,
    calculate_confidence,  # direct sources only
    propagate,             # with belief propagation through dependency chain
    find_contradictions,   # semantic when available, keyword fallback
    ReasoningGuard,
)
```

---

## Roadmap

- [x] Confidence vectors with noisy-OR source pooling
- [x] Temporal decay by source type (MATHEMATICAL to ANECDOTAL)
- [x] Belief propagation — foundations affect dependent claims
- [x] Semantic contradiction detection via sentence embeddings
- [x] Reasoning guard for agent pre-flight checks
- [x] Published to PyPI: `pip install veritas-epistemic`
- [ ] Active challenge mode — search for contradicting evidence automatically
- [ ] Cathedral integration — epistemic layer on top of persistent agent memory
- [ ] REST API for multi-agent use

---

## Cathedral integration

[Cathedral](https://cathedral-ai.com) gives AI agents persistent memory across sessions. Veritas is the reasoning layer that sits on top: Cathedral stores *what an agent remembers*, Veritas tracks *how well those memories hold up*.

Together: an agent knows its history and knows how much to trust it.

### Architecture

```
Cathedral                      Veritas
─────────────────────          ──────────────────────────────
memories with importance  -->  claims with confidence vectors
session snapshots         -->  temporal decay on sources
identity at t=0           -->  fragility tracking over time
```

These are independent layers. Run them in parallel and surface disagreement as signal — don't couple them. Coupling propagates fragility both ways.

### Composing by memory ID

The natural join: use Cathedral memory IDs as the `context` tag in Veritas. When a belief lives in both systems, you can cross-reference by ID.

```python
from cathedral import Cathedral
from veritas import VeritasDB, ReasoningGuard
from veritas.models import Claim, Source, SourceType, Stance

cathedral = Cathedral(api_key="cathedral_...")
db = VeritasDB("~/.veritas/veritas.db")
guard = ReasoningGuard(db)

# Agent wakes — load identity memories from Cathedral
wake_data = cathedral.wake()

for memory in wake_data.get("identity_memories", []):
    mem_id   = memory["id"]
    content  = memory["content"]
    importance = memory["importance"]

    # Register in Veritas under the Cathedral memory ID
    if not db.search(content[:60]):
        claim = Claim(
            statement=content,
            context=f"cathedral:{mem_id}",
            sources=[
                Source(
                    citation=f"Cathedral memory {mem_id}",
                    weight=importance,
                    stance=Stance.SUPPORTS,
                    source_type=SourceType.EMPIRICAL,
                )
            ],
        )
        db.add_claim(claim)
```

### The importance-fragility flag

Cathedral marks core identity memories at `importance=1.0`. If those same beliefs have a Veritas `fragility >= 0.7`, the agent is treating a shaky belief as maximally important — that combination should be surfaced explicitly.

```python
FRAGILITY_WARN = 0.70  # tune to taste

for memory in wake_data.get("identity_memories", []):
    if memory["importance"] < 1.0:
        continue
    result = guard.check(memory["content"][:120])
    if result.is_fragile and result.confidence > 0:
        cv = result.confidence
        # A high-importance memory with fragile epistemic support
        # means the agent's identity depends on a belief that would
        # collapse if its primary source were removed.
        print(f"[FLAG] importance=1.0 but fragility={cv:.2f}")
        print(f"       {memory['content'][:80]}...")
        for flag in result.flags:
            print(f"         - {flag}")
```

This doesn't mean the belief is wrong — it means the *evidence base* is thin. The right response is to find additional independent sources, not to lower the importance.

### Pre-action guard

Before acting on any recalled belief, check it:

```python
result = guard.check("the Cathedral API is reliable for production use")
if result.should_proceed:
    # act
elif result.verdict == "CAUTION":
    # act with caveats, log the flags
    for flag in result.flags:
        log.warning(flag)
else:
    # HALT — surface to the agent or user, don't act
    raise EpistemicHalt(result.reason)
```

See [`examples/cathedral_integration.py`](examples/cathedral_integration.py) for a full walkthrough.

---

## License

MIT
