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

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

Related MCP server: hw_rag_mcp

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.

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.

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

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

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):

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:

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.