Metadata-Version: 2.4
Name: empirica
Version: 1.2.4
Summary: Genuine AI epistemic self-assessment framework - Universal interface for single AI tracking
Author: Empirica Team
License-Expression: MIT
Keywords: ai,llm,epistemic,self-assessment,metacognition,calibration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: aiofiles>=23.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: httpx>=0.24
Requires-Dist: requests>=2.31.0
Requires-Dist: cryptography>=41.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: anthropic>=0.39.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: rich>=13.0
Requires-Dist: google-generativeai>=0.5
Requires-Dist: typer>=0.9
Provides-Extra: api
Requires-Dist: flask>=3.0; extra == "api"
Requires-Dist: flask-cors>=4.0; extra == "api"
Requires-Dist: fastapi>=0.104; extra == "api"
Requires-Dist: uvicorn>=0.24; extra == "api"
Provides-Extra: vector
Requires-Dist: qdrant-client>=1.7; extra == "vector"
Provides-Extra: vision
Requires-Dist: pytesseract>=0.3; extra == "vision"
Requires-Dist: pillow>=10.0; extra == "vision"
Requires-Dist: opencv-contrib-python>=4.8; extra == "vision"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: empirica[api,mcp,vector,vision]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Requires-Dist: pytest-cov>=4.1; extra == "test"
Requires-Dist: pytest-mock>=3.11; extra == "test"
Requires-Dist: dirty-equals>=0.7; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff>=0.1.0; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: pyright>=1.1.330; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: empirica[lint,test,typecheck]; extra == "dev"
Dynamic: license-file

# 🧠 Empirica - Epistemic Vector-Based Functional Self-Awareness Framework

> **AI agents that know what they know—and what they don't**

[![Version](https://img.shields.io/badge/version-1.2.3-blue)](https://github.com/Nubaeon/empirica/releases/tag/v1.2.3)
[![PyPI](https://img.shields.io/pypi/v/empirica)](https://pypi.org/project/empirica/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/Nubaeon/empirica/blob/main/LICENSE)
[![Docker](https://img.shields.io/badge/docker-nubaeon%2Fempirica-blue)](https://hub.docker.com/r/nubaeon/empirica)

## What's New in 1.2.3

- **🚦 Sentinel Safety Gates** - Human-in-the-loop gates (PROCEED/HALT/BRANCH/REVISE) that bound AI autonomy
- **🤖 Multi-Agent Spawning** - Spawn epistemic sub-agents with `agent-spawn`, aggregate findings with `agent-aggregate`
- **🎭 Persona System** - AI identity profiles that emerge from successful epistemic patterns (`persona-list`, `persona-promote`)
- **🔧 108 CLI Commands** - Full coverage including assessment, trajectory projection, and drift detection
- **🌙 3-Layer Signaling** - Moon phase indicators (🌑→🌕) for epistemic health at a glance
- **📈 Trajectory Projection** - Project epistemic learning curves with `trajectory-project`
- **🐢 Turtle Principle** - Recursive grounding: every claim must trace to verifiable source

## ⚡ Claude Code Quick Start

### What You Do vs What Claude Does

| You Do (Once) | Claude Does (Automatic) |
|---------------|------------------------|
| `pip install empirica` | Runs `project-bootstrap` to load prior learnings |
| Add snippet to `~/.claude/CLAUDE.md` | Logs findings as it works |
| Work normally | Runs CHECK gates before risky actions |
| | Saves what it learned at session end |

### Setup (2 minutes)

**Step 1: Install**
```bash
pip install empirica
```

**Step 2: Add to ~/.claude/CLAUDE.md**
Copy this to `~/.claude/CLAUDE.md` (Claude Code) or your AI's system prompt:

```markdown
# Empirica - Epistemic Self-Assessment

You have Empirica installed. Use it to track what you know and learn.

## Quick Start
```bash
# Start session
empirica session-create --ai-id claude-code --output json

# Before work: What do I know?
empirica preflight-submit -

# After work: What did I learn?
empirica postflight-submit -
```

## Core Vectors (0.0-1.0)
- **know**: Domain knowledge (0.7+ = ready)
- **uncertainty**: Doubt level (0.35- = ready)
- **context**: Information access
- **do**: Execution capability

## Log As You Work
```bash
empirica finding-log --finding "Discovered X" --impact 0.7
empirica unknown-log --unknown "Need to investigate Y"
```

## When Uncertain
Run CHECK gate: `empirica check-submit -`

Full docs: `empirica --help`
```

**Full setup guide:** [CLAUDE_CODE_SETUP.md](docs/guides/CLAUDE_CODE_SETUP.md) (hooks, MCP, troubleshooting)
**Full system prompt:** [CLAUDE.md](docs/system-prompts/CLAUDE.md) | [CANONICAL_CORE.md](docs/system-prompts/CANONICAL_CORE.md)

### Step 3: (Optional) MCP for Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "empirica": {
      "command": "empirica-mcp",
      "env": { "EMPIRICA_AI_ID": "claude-desktop" }
    }
  }
}
```

### Docker
```bash
docker pull nubaeon/empirica:1.2.3
```

### How It Works Day-to-Day

**You don't need to type Empirica commands.** Just talk to Claude normally:

| You Say (Natural Language) | Claude Does (Behind the Scenes) |
|---------------------------|--------------------------------|
| "Continue working on the auth refactor" | Runs `project-bootstrap` → loads what it learned last session |
| "I'm not sure about this approach" | Runs `check-submit` → assesses if it knows enough to proceed |
| "Good work, let's wrap up" | Runs `postflight-submit` → saves learnings for next time |

**What is `project-bootstrap`?**

When Claude starts a session, `project-bootstrap` loads ~800 tokens of structured context:
```
📊 Epistemic State: know=0.85, uncertainty=0.15
🎯 Active Goals: Refactor auth module (in_progress)
💡 Recent Findings: "Auth uses JWT with 15min expiry"
❓ Open Unknowns: "Token rotation mechanism unclear"
```

This replaces 200k tokens of conversation history with just the important bits.

**Will Claude ignore the commands?**

Sometimes, especially mid-task. But after a memory compact (when context summarizes), Claude naturally looks for context—that's when bootstrap shines. The CLAUDE.md instructions make this reliable.

### Live Metacognitive Signal

With Claude Code hooks enabled, you see Claude's epistemic state in real-time:

```
[empirica] ⚡79% │ ⚡ PRAXIC │ POSTFLIGHT │ K:80% U:20% C:90% │ Δ K:+0.30 U:-0.30 C:+0.30 │ ✓ stable
```

**What this tells you:**
- **⚡79%** - Overall epistemic confidence
- **PRAXIC** - Claude is in action mode (vs NOETIC = investigation mode)
- **POSTFLIGHT** - Just completed a task and logged learnings
- **K:80% U:20%** - 80% knowledge, 20% uncertainty (healthy state)
- **Δ K:+0.30** - Gained 30% knowledge this session (learning delta)
- **✓ stable** - No epistemic drift detected

**Why this matters:** You can see when Claude is uncertain before it acts, when it's learning, and when it might be drifting from reality. No more guessing if Claude actually knows what it's doing.

## What is Empirica?

**Empirica is an epistemic self-awareness framework for AI agents** that enables genuine self-assessment, systematic learning tracking, and effective multi-agent collaboration.

Unlike traditional AI tools that rely on static prompts or heuristic-based evaluation, Empirica provides **13-dimensional epistemic vector tracking** that allows AI agents to know what they know (and don't know) with measurable precision.

### Core Philosophy: Epistemic Self-Awareness

**The Problem:** AI agents often exhibit "confident ignorance" - they confidently generate responses about topics they don't actually understand.

**The Solution:** Empirica enables **genuine epistemic self-assessment** through:

1. **13-Dimensional Vector Space** - Track knowledge, capability, context, and uncertainty across multiple dimensions
2. **CASCADE Workflow** - Structured reasoning process with explicit epistemic gates
3. **Dynamic Context Loading** - Resume work with compressed project memory
4. **Multi-Agent Coordination** - Seamless handoffs between AI agents

### Key Features

- ✅ **Honest uncertainty tracking**: "I don't know" becomes a measured response
- ✅ **Focused investigation**: Direct effort where knowledge gaps exist
- ✅ **Genuine learning measurement**: Track what you learned, not just what you did
- ✅ **Session continuity**: Resume work across sessions without losing context
- ✅ **Multi-agent coordination**: Share epistemic state across AI teams

**Result:** AI you can trust—not because it's always right, but because **it knows when it might be wrong**.

## 🚀 Quick Start

### Installation

#### PyPI (Recommended)

```bash
# Core installation
pip install empirica

# With API/dashboard features
pip install empirica[api]

# With vector search
pip install empirica[vector]

# Everything
pip install empirica[all]
```

#### Docker

```bash
# Pull the latest image
docker pull nubaeon/empirica:1.2.3

# Run a command
docker run -it nubaeon/empirica:1.2.3 empirica --help

# Interactive session with persistent data
docker run -it -v $(pwd)/.empirica:/data/.empirica nubaeon/empirica:1.2.3 /bin/bash
```

#### From Source

```bash
# Latest stable release
pip install git+https://github.com/Nubaeon/empirica.git@v1.2.3

# Development branch
pip install git+https://github.com/Nubaeon/empirica.git@develop
```

### Initialize a New Project

```bash
# Navigate to your git repository
cd your-project
git init

# Initialize Empirica
empirica project-init
```

### Your First Session

```bash
# AI-first JSON mode (recommended for AI agents)
echo '{"ai_id": "myagent", "session_type": "development"}' | empirica session-create -
```

## 🎯 Core Workflow: CASCADE

Empirica uses **CASCADE** - a metacognitive workflow with explicit epistemic phases:

```bash
# 1. PREFLIGHT: Assess what you know BEFORE starting
cat > preflight.json <<EOF
{
  "session_id": "abc-123",
  "vectors": {
    "engagement": 0.8,
    "foundation": {"know": 0.6, "do": 0.7, "context": 0.5},
    "comprehension": {"clarity": 0.7, "coherence": 0.8, "signal": 0.6, "density": 0.7},
    "execution": {"state": 0.5, "change": 0.4, "completion": 0.3, "impact": 0.5},
    "uncertainty": 0.4
  },
  "reasoning": "Starting with moderate knowledge of OAuth2..."
}
EOF
cat preflight.json | empirica preflight-submit -

# 2. WORK: Do your actual implementation
#    Use CHECK gates as needed for decision points

# 3. POSTFLIGHT: Measure what you ACTUALLY learned
cat > postflight.json <<EOF
{
  "session_id": "abc-123",
  "vectors": {
    "engagement": 0.9,
    "foundation": {"know": 0.85, "do": 0.9, "context": 0.8},
    "comprehension": {"clarity": 0.9, "coherence": 0.9, "signal": 0.85, "density": 0.8},
    "execution": {"state": 0.9, "change": 0.85, "completion": 1.0, "impact": 0.8},
    "uncertainty": 0.15
  },
  "reasoning": "Successfully implemented OAuth2, learned token refresh patterns"
}
EOF
cat postflight.json | empirica postflight-submit -
```

**Result:** Quantified learning (know: +0.25, uncertainty: -0.25)

## ✨ Key Features

### 📊 Epistemic Self-Assessment (13 Vectors)

Track knowledge across 3 tiers:
- **Tier 0 (Foundation):** engagement, know, do, context
- **Tier 1 (Comprehension):** clarity, coherence, signal, density
- **Tier 2 (Execution):** state, change, completion, impact
- **Meta:** uncertainty (explicit tracking)

### 🎯 Goal-Driven Task Management

```bash
# Create goals with epistemic scope
echo '{
  "session_id": "abc-123",
  "objective": "Implement OAuth2 authentication",
  "scope": {
    "breadth": 0.6,
    "duration": 0.4,
    "coordination": 0.3
  },
  "success_criteria": ["Auth works", "Tests pass"],
  "estimated_complexity": 0.65
}' | empirica goals-create -
```

### 🔄 Session Continuity

```bash
# Load project context dynamically (~800 tokens)
empirica project-bootstrap --project-id <PROJECT_ID>
```

### 🤝 Multi-Agent Coordination

**Spawn epistemic sub-agents:**
```bash
# Spawn a sub-agent for parallel investigation
empirica agent-spawn --session-id <ID> --task "Investigate auth patterns" --depth medium

# Sub-agent reports back
empirica agent-report --session-id <SUB_ID> --findings '[...]' --confidence 0.8

# Aggregate findings from multiple agents
empirica agent-aggregate --parent-session-id <ID> --merge-strategy weighted
```

**Share epistemic state via git notes:**
```bash
# Push your epistemic checkpoints
git push origin refs/notes/empirica/*

# Pull team member's state
git fetch origin refs/notes/empirica/*:refs/notes/empirica/*
```

### 🚦 Sentinel Safety Gates

**Bounded AI autonomy with human oversight:**
```bash
# Check if operation is safe to proceed
empirica sentinel-check --operation '{"type": "code_generation", "scope": "high"}' --session-id <ID>

# Returns: PROCEED | HALT | BRANCH | REVISE

# Orchestrate multi-step workflow with gates
empirica sentinel-orchestrate --workflow workflow.json --session-id <ID>
```

**Gate types:**
- `PROCEED` - Safe to continue autonomously
- `HALT` - Requires human approval before continuing
- `BRANCH` - Spawn investigation before proceeding
- `REVISE` - Modify approach and resubmit

### 🎭 Persona System

**AI identity profiles that emerge from successful patterns:**
```bash
# List available personas
empirica persona-list

# Find persona matching current task
empirica persona-find --task "security audit" --session-id <ID>

# Promote traits based on successful outcomes
empirica persona-promote --persona-id researcher --trait thoroughness --evidence "Found 3 critical bugs"
```

### 📈 Drift Detection & Trajectory

**Monitor epistemic health and project learning curves:**
```bash
# Check for behavioral drift
empirica check-drift --session-id <ID>

# Project epistemic trajectory
empirica trajectory-project --session-id <ID> --horizon 5

# Assess current epistemic state
empirica assess-state --session-id <ID> --include-history
```

**Moon phase indicators for health at a glance:**
- 🌑 Critical (coverage < 25%)
- 🌒 Low (25-50%)
- 🌓 Moderate (50-75%)
- 🌔 Good (75-90%)
- 🌕 Excellent (90%+)

## 📦 Optional Integrations

### BEADS Issue Tracking

**Install BEADS** (separate Rust project):
```bash
cargo install beads
```

### MCP Server (Model Context Protocol)

**For AI tools that support MCP:**
```bash
# Install MCP server
pip install empirica-mcp

# Run server
empirica-mcp
```

**Features:** 57 tools including 9 Human Copilot tools for enhanced human oversight.

### Claude Code Integration

**Automatic epistemic continuity across memory compacts:**
```bash
# Install plugin (bundled with Empirica)
./scripts/install_claude_plugin.sh
```

### Vector Search (Qdrant)

```bash
pip install empirica[vector]

# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant

# Embed docs
empirica project-embed --project-id <PROJECT_ID>

# Search
empirica project-search --project-id <PROJECT_ID> --task "oauth2"
```

## 📚 Documentation

### Getting Started
- 📖 [First-Time Setup](https://github.com/Nubaeon/empirica/blob/main/docs/guides/FIRST_TIME_SETUP.md)
- 🚀 [Empirica Explained Simply](https://github.com/Nubaeon/empirica/blob/main/docs/EMPIRICA_EXPLAINED_SIMPLE.md)

### Guides
- 🎯 [CASCADE Workflow](https://github.com/Nubaeon/empirica/blob/main/docs/CASCADE_WORKFLOW.md)
- 📊 [Epistemic Vectors](https://github.com/Nubaeon/empirica/blob/main/docs/archive/v3/production/05_EPISTEMIC_VECTORS.md)

### Reference
- 📋 [CLI Commands](https://github.com/Nubaeon/empirica/blob/main/docs/reference/CLI_COMMANDS_COMPLETE.md)
- 🗄️ [Database Schema](https://github.com/Nubaeon/empirica/blob/main/docs/reference/DATABASE_SCHEMA_GENERATED.md)

## 🔒 Privacy & Data Isolation

**Your data is isolated per-repo:**
- ✅ `.empirica/` - Local SQLite database (gitignored)
- ✅ `.git/refs/notes/empirica/*` - Epistemic checkpoints (local by default)
- ✅ `.beads/` - BEADS database (gitignored)

## 🛠️ Development

### Running Tests

```bash
# Core tests
pytest tests/

# Integration tests
pytest tests/integration/
```

### Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📊 System Requirements

- **Python:** 3.11+
- **Git:** Required for epistemic checkpoints
- **Optional:** Docker (for Qdrant), Rust/Cargo (for BEADS)

## 🎓 Learn More

### Research & Concepts
- [Why Empirica?](https://github.com/Nubaeon/empirica/blob/main/WHY_EMPIRICA.md)
- [Epistemic Architecture](https://github.com/Nubaeon/empirica/blob/main/docs/architecture/EMPIRICA_COMPLETE_ARCHITECTURE.md)

### Use Cases
- Research & Development
- Multi-Agent Teams
- Long-Running Projects
- Training Data Generation
- Epistemic Audit Trails

## 🔗 Related Projects

- **[Empirica MCP](./empirica-mcp/)** - Model Context Protocol server for Empirica integration
- **[Empirica EPRE](https://github.com/Nubaeon/empirica-epre)** - Epistemic Pattern Recognition Engine

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/Nubaeon/empirica/issues)
- **Discussions:** [GitHub Discussions](https://github.com/Nubaeon/empirica/discussions)
- **Documentation:** [docs/](https://github.com/Nubaeon/empirica/tree/main/docs)

## 📜 License

MIT License - Maximum adoption, trust-aligned with Empirica's transparency principles.

See [LICENSE](LICENSE) for details.

---

**Built with genuine epistemic transparency** 🧠✨
