# Cheap Research v1.0.0

A bounded evidence review engine. Give it a claim and a document corpus - it extracts relevant evidence, detects contradictions, and produces auditable evidence packets. No hallucinations, no global truth claims, no open-web research.

## What it does

1. **Ingest** PDF, TXT, MD, DOCX, DOC, HTML, RTF, EPUB documents
2. **Extract** evidence spans relevant to your claim
3. **Detect** contradictions between claim and corpus
4. **Render** markdown evidence packets with caveats
5. **Audit** immutable hash-chained audit trail

## Trust posture

- **Fails closed** - enforcement engine blocks invalid authority transitions
- **Bounded corpus** - cannot make claims outside provided documents
- **Explicit caveats** - every packet states limitations
- **No global truth** - "not established in corpus" not "false"
- **Human review required** - claims need explicit reviewer sign-off

## MCP Tools

| Tool | Description |
|------|-------------|
| `research_start` | Ingest corpus, assess claim, produce evidence packet |
| `research_status` | Get run state and evidence summary |
| `research_getEvidence` | Get top relevant spans + contradictions |
| `research_getPacket` | Get full markdown assessment report |
| `research_audit` | Run compliance integrity audit |
| `corpus_topics` | List available paper topics for download |
| `corpus_list` | List all papers in curated library (filterable) |
| `corpus_load` | Download seminal ML papers to corpus directory |

## Quick Start: Download Papers

Use `corpus_load` to download a curated set of foundational ML papers:

```javascript
// Download ALL papers to your corpus
corpus_load({ corpus_path: "/path/to/cheap-research/corpus" })

// Or download specific topics
corpus_load({
  corpus_path: "/path/to/corpus",
  topics: ["transformers", "optimization"]
})

// Or specific papers by ID
corpus_load({
  corpus_path: "/path/to/corpus",
  paper_ids: ["attention", "bert", "resnet"]
})
```

**Available topics:** `transformers`, `foundations`, `optimization`, `reinforcement`, `generative`, `representations`, `efficiency`

**Papers included:** Attention Is All You Need, BERT, GPT, GPT-3, ResNet, AlexNet, LSTM, Adam, Batch Norm, Dropout, GANs, VAE, Diffusion Models, Vision Transformer, Word2Vec, DQN, Knowledge Distillation, and more (22 papers total).

## Install

```bash
git clone https://github.com/your-org/cheap-research.git
cd cheap-research
npm install
npm run build
```

## Adding to Your AI Assistant

This server uses the Model Context Protocol (MCP). Here's how to connect it to your AI:

### Claude (Claude Code CLI / Claude Desktop)

1. Open your MCP config file:
   - **Claude Code**: `~/.claude.json`
   - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

2. Add the server to `mcpServers`:

```json
{
  "mcpServers": {
    "cheap-research": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/cheap-research/node_modules/.bin/tsx",
        "--tsconfig",
        "/ABSOLUTE/PATH/TO/cheap-research/tsconfig.base.json",
        "/ABSOLUTE/PATH/TO/cheap-research/apps/mcp-server/src/index.ts"
      ]
    }
  }
}
```

3. Replace `/ABSOLUTE/PATH/TO/` with the actual path where you cloned the repo.

4. Restart Claude Code or Claude Desktop.

5. Type `/mcp` in Claude Code to verify the server is connected.

### Other MCP-compatible AI Tools

Any AI tool that supports MCP can use this server. Point it to run the `npm run mcp` command or use the config format above. Check your tool's documentation for MCP server configuration.

## Run as MCP Server (manual)

```bash
npm run mcp
```

This starts the server in stdio mode, ready for MCP clients.

## Example

```javascript
// Start research on a claim
research_start({
  task_type: "bounded_doc_claim_assessment",
  target_claim: "Attention mechanisms enable Transformers to model long-range dependencies",
  entity: "Transformer architecture",
  feature: "attention mechanism",
  scope: "Assess based on provided neural network papers",
  corpus_path: "/path/to/corpus"
})

// Returns: { run_id, status: "completed", assessment: "qualified", ... }
```

## Supported Formats

| Format | Extension | Parser |
|--------|-----------|--------|
| PDF | `.pdf` | pdf-parse |
| Text | `.txt` | native |
| Markdown | `.md` | native |
| Word | `.docx` | mammoth |
| Word (legacy) | `.doc` | mammoth + fallback |
| HTML | `.html`, `.htm` | cheerio |
| RTF | `.rtf` | rtf-parser |
| EPUB | `.epub` | epub2 |

## What's NOT included (intentional)

- Open-web research
- Autonomous recommendations
- Confidence scores
- Free-form LLM synthesis
- Automatic operational acceptance
- Vector embeddings / semantic search

## Architecture

```
corpus/           → ingestCorpus() → MemoryStore
                                  ↓
claim + evidence  → findRelevantSpans() → scored spans
                                  ↓
                  → detectContradictions() → flagged spans
                                  ↓
                  → createClaimCandidate() → enforcement check
                                  ↓
                  → renderPacketMarkdown() → evidence packet
                                  ↓
                  → publishPacket() → audit log
```

## State Machines

Claims, findings, packets all have strict state transitions enforced by the enforcement engine. Illegal transitions are blocked with explicit blockers.

## Audit Trail

Hash-chained immutable audit log. Every action recorded with:
- Actor context (who)
- Object reference (what)
- Event type (action)
- Payload (details)
- Chain hash (integrity)

## License

MIT