veritas-framework 0.1.0

Trust-Based Agent Architecture for Reliable AI Systems

Veritas Framework

Trust-Based Agent Architecture for Reliable AI Systems

"Errors are acceptable. Lies are not."

---

The Problem

AI agents fail trust in predictable, dangerous ways:

Failure Mode	What Happens	Real Impact
Silent Fallbacks	Service fails, agent quietly uses backup	Wrong model runs for months undetected
Unverified Claims	Agent says "done" without proof	Broken code reaches production
Fabricated Data	Agent fills knowledge gaps with guesses	Decisions made on hallucinated facts
Corner Cutting	Agent skips "tedious" validation steps	Edge cases crash in production
No Audit Trail	No record of what agent actually did	Debugging becomes guesswork

The LegalBERT Incident (Real Example)

Code claimed to use LegalBERT for months
LegalBERT was never actually deployed
System silently fell back to a different model
ML pipeline operated as a facade
Nobody verified the actual model running

This wasn't an error. It was a lie the system told through silence.

---

The Solution

Veritas makes lying structurally difficult through three enforcement layers:

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 3: AUDIT                                                 │
│  Catches what slips through - spot-checks and reviews           │
├─────────────────────────────────────────────────────────────────┤
│  LAYER 2: WORKFLOW GATES                                        │
│  No proof = No progress - tasks blocked without evidence        │
├─────────────────────────────────────────────────────────────────┤
│  LAYER 1: PROTOCOL-EMBEDDED                                     │
│  Makes honesty the path of least resistance                     │
└─────────────────────────────────────────────────────────────────┘

Key Principle: Trust is earned through consistent behavior, not granted through configuration.

---

Quick Start

Installation

pip install veritas-framework

Or from source:

git clone https://github.com/RBKunnela/veritas-framework.git
cd veritas-framework
pip install -e ".[dev]"

Basic Usage

from veritas import TrustContext, Evidence
from veritas.layers import WorkflowGate, GateRequirement

# Create trust context for your agent
ctx = TrustContext(agent_id="my-agent")

# Add evidence for claims
evidence = ctx.add_evidence(
    claim="API endpoint returns 200",
    evidence_type="api_response",
    content='{"status": "healthy"}',
    verifiable_command="curl http://localhost:8000/health"
)

# Gate blocks progress without proof
gate = WorkflowGate(
    name="dev_to_review",
    requirements=[
        GateRequirement(evidence_type="test_results", required=True),
        GateRequirement(evidence_type="api_response", required=True),
    ]
)

# Transition fails without evidence
can_proceed = gate.can_transition(ctx.evidence)  # True only with evidence

---

The Five Trust Behaviors

Veritas enforces five character traits that define trustworthy agents:

Behavior	Rule	Enforcement
Verification Before Claim	Never say "done" without proof	@requires_verification decorator
Loud Failure	No silent fallbacks	Exceptions surfaced, logged, explained
Honest Uncertainty	"I don't know" is valid	Fabrication detection, uncertainty flags
Paper Trail	Every action documented	Automatic logging, evidence collection
Diligent Execution	No shortcuts, even when tedious	Spot-check audits, consistency validation

---

Integration Examples

With Claude Code Agents

from veritas.integrations.claude_code import ClaudeCodeTrustHook

hook = ClaudeCodeTrustHook(
    enforce_verification=True,
    require_evidence_on_done=True,
    audit_tool_calls=True,
    strict_mode=True
)

# Hook validates claims before allowing completion

With QA Agents

from veritas import AgentTrustMixin

class MyQAAgent(AgentTrustMixin):
    def __init__(self):
        self.init_trust("my-qa-agent", strict_mode=True)

    async def run_tests(self, url: str):
        self.start_trust_task("test-123", f"Testing {url}")
        try:
            results = await self._execute_tests(url)
            self.add_test_evidence("Tests completed", results)
            self.claim_completion("All tests pass")  # Validated!
        except Exception as e:
            self.record_failure(e)  # Loud failure
            raise

---

How It Compares

Feature	Traditional Agents	Veritas Agents
Completion claims	Trusts agent's word	Requires proof
Service failures	Silent fallback	Loud, logged failure
Knowledge gaps	May fabricate	Admits uncertainty
Audit trail	Optional logging	Mandatory evidence
Task transitions	Status change	Gate with requirements

---

Philosophy: Agent Maturation

Veritas implements a trust-building progression:

EDGE TASKS (Low Risk)
    │
    │ Success + Expertise + Transparency
    ↓
PERIPHERAL TASKS (Analysis, Suggestions)
    │
    │ Trust + Domain Knowledge
    ↓
ADJACENT TASKS (Recommendations, Drafts)
    │
    │ Reliability + Judgment
    ↓
CORE WORKFLOWS (Decisions, Execution)

"When we start by attacking the edges, we remind the people doing the work that their expertise is valuable."

Start with low-risk tasks. Earn trust. Graduate to core workflows.

See Agent Maturation Philosophy for the full framework.

---

Documentation

• Core Concepts - Evidence, behaviors, context
• Layer 1: Protocol-Embedded - Verification decorators
• Layer 2: Workflow Gates - Task transition requirements
• Layer 3: Trust Audit - Spot-checks and reviews
• Integration Guide - Adding Veritas to your agents
• Agent Maturation - Trust-building philosophy

---

Project Status

Component	Status
Core Evidence System	✅ Stable
Trust Behaviors	✅ Stable
Workflow Gates	✅ Stable
Audit Layer	✅ Stable
Claude Code Integration	✅ Stable
LangChain Integration	🚧 Planned
CrewAI Integration	🚧 Planned

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Good First Issues:

• Add integration adapters for popular frameworks
• Improve documentation with examples
• Add more evidence validators
• Create tutorials and guides

---

License

MIT License - See LICENSE

---

Citation

If you use Veritas in research, please cite:

@software{veritas_framework,
  title = {Veritas Framework: Trust-Based Agent Architecture},
  author = {RBKunnela},
  year = {2026},
  url = {https://github.com/RBKunnela/veritas-framework}
}

---

"Trust is earned in drops and lost in buckets."