# Alpha Library

Centralized trading knowledge base. Book summaries, document chunks, structured strategies. SQLite + FTS5 full-text search, exposed via CLI and MCP server.

> ### 📚 Come for the summaries, or bring your own books
>
> **[`public/`](public/) ships 174 book summaries** — ~1.2 M characters distilled from a shelf of
> trading, investing and market-structure literature, in a ready-to-search SQLite file. Point
> `DB_PATH` at it and every tool works immediately. That is the knowledge, shared.
>
> **No source material ships.** `inbox/` (the books themselves), `references/` (purchased course
> material and third-party playbooks), `strategies/` (working methods) and the full `data/`
> database are all gitignored.
>
> The full database is the non-obvious one: its `documents` table holds the **complete chunked
> text** of every ingested book — 13.9 M characters — so publishing it would redistribute those
> books more thoroughly than shipping the EPUBs would, and far less visibly. The public export
> carries the summaries only, and the build script drops the whole table rather than filtering
> it, because an allowlist stays correct only until someone forgets.
>
> To build your own library instead, `examples/` documents the file format each parser expects.

## Setup

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
copy .env.example .env
```

## Seed content

Point it at whatever you own. Every ingest command is idempotent — re-running skips what is
already in, so a repeated batch is safe. Pass `--replace` to overwrite deliberately.

```powershell
python -m alpha_library ingest-references                      # bulk-ingest references/
python -m alpha_library ingest-document "path\to\manual.epub" --source "Manual Name"
python -m alpha_library ingest-book path\to\summary.md
python -m alpha_library stats
```

## Search: ask it a question, not a keyword

Search runs in three stages. You do not have to think about them; this is what happens.

1. **Keyword** — exact terms, via SQLite FTS5. `"iron condor"` goes straight to the iron condor
   chapter. Unbeatable when you know the word.
2. **Meaning** — finds passages *about* your question even when they share no words with it.
3. **Reranking** — reads the shortlist against your question and keeps the best few.

The difference on this library, measured:

```
"why do I keep sabotaging myself after a win"
   keyword:  0 results
   meaning:  Trading in the Zone > Shaping Your Mental Environment
             "...they haven't yet learned how to counteract the negative
              effects of euphoria..."

"position sizing after a losing streak"
   keyword:  0 results
   meaning:  The Options Field Manual > Ch 10: Position Sizing
             "...10% risk per trade. Ten losses = 100%..."
```

Neither question shares enough words with its answer to be findable by keyword. Both are
answered well. Ask in plain language.

### Switching it on

Meaning search is an **optional extra** — it pulls in ~150 MB of model runtime, and the library
is fully usable without it.

```powershell
pip install -e ".[semantic]"
python -m alpha_library build-index      # once, ~20 min. Then only new material.
```

Without it everything still works on keyword search, and every result says
`search_mode: "keyword only"` with a note explaining how to enable the rest — so a degraded
answer never passes for a complete one.

**Speed:** keyword ~25 ms; the full stack ~1.5 s, nearly all of it reranking. Pass
`--keyword-only` (CLI) or `keyword_only=True` (MCP) when you know the exact term and want it
instant.

## CLI

```powershell
python -m alpha_library search "how much should I risk on one trade"
python -m alpha_library search "iron condor" --keyword-only
python -m alpha_library search "gamma" --scope documents --limit 5
python -m alpha_library build-index
python -m alpha_library stats                    # includes whether meaning search is on
python -m alpha_library ingest-book path\to\book.md
python -m alpha_library ingest-strategy path\to\strat.md
python -m alpha_library ingest-document path\to\doc.epub
python -m alpha_library export --output backup.json
```

## Tests

```powershell
pip install -e ".[dev]"
python -m pytest tests
```

28 tests, all offline, each building its own throwaway database — nothing touches the real
library. They pin the failure modes that are **silent**: resolving a title to the wrong book,
reading a database that isn't there, an oversized listing, and a malformed query coming back as
an empty result.

## MCP Server

Standalone run (for testing):

```powershell
python server.py                                # stdio, what an MCP client uses
python server.py --transport http --port 8773   # over the network
```

Register with Claude Code (one-time, user scope so it's available everywhere). **Use the path
where you actually cloned it** — this is a full absolute path and it will not follow the folder
if you move it:

```powershell
claude mcp add alpha_library --scope user -- "<repo>\.venv\Scripts\python.exe" "<repo>\server.py"
```

Verify with `claude mcp list`. After registration the 9 tools appear in new sessions as
`mcp__alpha_library__*` (search_knowledge, get_book_summary, get_strategy, get_document_chunk,
list_books, list_categories, list_strategies, add_book_summary, add_strategy).

### How to use it: search finds, get_* reads

Search returns ranked **pointers** — identity plus the passage that matched, never full text,
because a handful of whole book summaries exceeds the tool-output limit and the call then fails
outright. Hits carry an `id`; pass it back for an exact read:

```
search_knowledge("gamma exposure")   ->  { id: 68, title: "...", match_snippet: "..." }
get_book_summary(book_id=68)         ->  the full summary, no ambiguity
```

`get_book_summary` and `get_strategy` also accept a title or name for convenience — but a text
match can hit several things ("trading" matches 27 of the books), and in that case they return
the **candidate list** rather than picking one and sounding certain. Prefer the id.

`list_books` is paged and always reports the true `total`; call `list_categories()` first to
find the shelf you want.