# 🧠 Empirica - Honest AI Through Epistemic Self-Awareness

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

[![Version](https://img.shields.io/badge/version-1.0.3-blue)](https://github.com/Nubaeon/empirica/releases/tag/v1.0.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 is Empirica?

**Empirica enables AI agents to genuinely assess their knowledge and uncertainty.**

Instead of false confidence and hallucinations, Empirica provides:
- ✅ **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

Choose your preferred installation method:

#### 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]
```

#### Homebrew (macOS/Linux)

```bash
brew tap nubaeon/tap
brew install empirica
```

#### Docker

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

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

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

#### Chocolatey (Windows)

```powershell
choco install empirica
```

#### From Source

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

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

**🆕 First-time user?** → [Installation Guide](https://github.com/Nubaeon/empirica/blob/main/docs/production/02_INSTALLATION.md)

### Initialize a New Project

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

# Initialize Empirica (creates config files, optional BEADS integration)
empirica project-init

# Follow interactive prompts:
# - Project name
# - Enable BEADS issue tracking? (y/N)
# - Create documentation index template? (y/N)
```

**Result:**
- ✅ `.empirica/config.yaml` - Infrastructure settings
- ✅ `.empirica/project.yaml` - Project metadata & BEADS config
- ✅ `docs/SEMANTIC_INDEX.yaml` - Documentation index (optional)
- ✅ Project registered in database

### Your First Session

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

# Legacy CLI (still supported)
empirica session-create --ai-id myagent --output json
```

**Output:**
```json
{
  "ok": true,
  "session_id": "abc-123-...",
  "project_id": "xyz-789-...",
  "message": "Session created successfully"
}
```

---

## 🎯 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 -
```

**Integrates with BEADS** (issue tracking) for dependency-aware workflows.

### 🔄 Session Continuity

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

**Shows:**
- Recent findings (what was learned)
- Open unknowns (what's unclear)
- Dead ends (what didn't work)
- Reference docs & skills

### 🤝 Multi-Agent Coordination

**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/*
```

**Privacy:** You control what gets shared!

---

## 📦 Optional Integrations

### BEADS Issue Tracking

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

**Features:**
- Dependency-aware task tracking
- Git-friendly (JSONL format)
- AI-optimized JSON output
- Auto-links with Empirica goals

**Learn more:** [BEADS Integration Guide](https://github.com/Nubaeon/empirica/blob/main/docs/integrations/BEADS_GOALS_READY_GUIDE.md)

### 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"
```

### API & Dashboard

```bash
pip install empirica[api]

# Start monitoring dashboard
empirica monitor
```

---

## 📚 Documentation

### Getting Started
- 📖 [First-Time Setup](https://github.com/Nubaeon/empirica/blob/main/docs/guides/FIRST_TIME_SETUP.md) - Data isolation & privacy
- 🚀 [Empirica Explained Simply](https://github.com/Nubaeon/empirica/blob/main/docs/EMPIRICA_EXPLAINED_SIMPLE.md) - Core concepts
- 📘 [System Prompt (v4.1)](https://github.com/Nubaeon/empirica/blob/main/.github/copilot-instructions.md) - AI-first JSON reference

### 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)
- 🎯 [Goal Tree Usage](https://github.com/Nubaeon/empirica/blob/main/docs/guides/GOAL_TREE_USAGE_GUIDE.md)
- 🤝 [Multi-Agent Teams](https://github.com/Nubaeon/empirica/blob/main/docs/archive/v3/production/26_CROSS_AI_COORDINATION.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)
- 🐍 [Python API](https://github.com/Nubaeon/empirica/blob/main/docs/reference/PYTHON_API_GENERATED.md)
- ⚙️ [Configuration](https://github.com/Nubaeon/empirica/blob/main/docs/reference/CONFIGURATION_REFERENCE.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)

**Each user gets a clean slate** - no inherited data from other users or projects.

---

## 🛠️ Development

### Running Tests

```bash
# Core tests
pytest tests/

# Integration tests
pytest tests/integration/

# MCP tests
pytest tests/mcp/
```

### 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)
- [Visual Guide](https://github.com/Nubaeon/empirica/blob/main/docs/architecture/EMPIRICA_VISUAL_GUIDE.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 (privacy-preserving platform integrations for Twitter, Slack, Discord, and more)

---

## 📞 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** 🧠✨
