Conjecture: Evidence-Based Reasoning Framework

A framework that forces LLMs to validate assumptions, fact-check sources, and explore/prove/disprove ideas before responding. Recursively breaks down knowledge into verifiable claims for reliable, trustworthy responses.

Core Philosophy: Claims Are NOT Facts

All knowledge is provisional claims with confidence scores — never facts. Claims are impressions, assumptions, observations, and conjectures that may be wrong and subject to revision.

What It Does

• Claim Management: Create, search, and analyze evidence-based claims
• Confidence Scoring: Track uncertainty with 0.0-1.0 confidence scores
• Semantic Search: Find relevant claims using natural language
• Multi-Provider LLM: Claude Agent SDK (primary), plus local/custom endpoints
• Provenance Tracking: Trace any assertion back through its evidence chain

Quick Start

# Clone and install
git clone <repository-url>
cd Conjecture
pip install -r requirements.txt

# Run Conjecture
python conjecture

# Test setup
python conjecture validate

Configuration

Conjecture uses hierarchical JSON configuration:

1. Workspace: .conjecture/config.json
2. User: ~/.conjecture/config.json
3. Default: src/config/default_config.json

Claude Agent SDK handles Claude authentication. Custom OpenAI/Anthropic-compatible endpoints configured via JSON.

See CHOICES.md for all configuration choices.

Architecture

4-Layer Architecture:

1. Presentation (src/cli/): User interaction (CLI, TUI, Web, MCP)
2. Endpoint (src/endpoint/): Public API
3. Process (src/process/): Intelligence and context building
4. Data (src/data/): Universal claim storage (SQLite + FAISS)

See specs/architecture.md for details.

Testing

# Run all tests
python -m pytest tests/ --cov=src

# By category
python -m pytest tests/ -m "unit"
python -m pytest tests/ -m "integration"

Project Structure

Conjecture/
├── CHOICES.md           # Source of Plan — all project choices
├── CLAUDE.md            # Agent instructions
├── README.md            # This file
├── src/
│   ├── cli/             # Presentation layer
│   ├── endpoint/        # Public API
│   ├── process/         # Intelligence layer
│   └── data/            # Storage layer
├── specs/               # Specifications
├── docs/                # User guides
└── tests/               # Test suites

Key Documentation

Document	Purpose
CHOICES.md	Source of Plan — all project choices
CLAUDE.md	Agent instructions
specs/architecture.md	4-layer architecture
specs/requirements.md	System requirements
docs/claims_philosophy.md	Claims philosophy

Contributing

1. Read CHOICES.md before proposing changes
2. Use /choose-wisely to modify project choices
3. Run tests before committing
4. Follow existing code patterns

License

[Add license information here]

---

Conjecture — Making evidence-based reasoning accessible and transparent.