Fable — a technology intelligence engine

What technologies matter, why do they matter, and what opportunities do they create?

Fable continuously observes the open-source ecosystem and turns raw engineering signals into technology intelligence: scored, evidence-bound reports on where technology is heading — built toward forecasting and, ultimately, opportunity discovery.

Not a GitHub analytics dashboard. The guiding principle:

Raw data → Knowledge → Intelligence → Prediction → Opportunity

Stars tell you what is popular. Fable is built to answer what is quietly becoming inevitable — and eventually, what should someone build next?

Status

Phase 1 (vertical slice) — working. One command produces a technology intelligence report from live GitHub data:

uv run fable report "llm inference"

Output: a ranked, scored, evidence-bound markdown report covering engineering velocity, contributor health, bus factor, release discipline, and momentum for the repositories that define a technology. See a real generated example in examples/.

Quickstart

Requires uv (Python is handled for you).

git clone https://github.com/saix0x0/project-1
cd project-1
./scripts/setup.sh                     # uv sync + a macOS venv fix (see docs/DECISIONS.md D12)
export GITHUB_TOKEN=$(gh auth token)   # or any GitHub PAT; unauthenticated works but is rate-limited
uv run fable report "llm inference"

Reports land in reports/, raw snapshots in data/ (both gitignored — they're your data).

uv run fable report "rust gpu" --limit 20      # more repos
uv run fable snapshot vllm-project/vllm        # snapshot a single repo
uv run pytest                                   # run tests

How it works (Phase 1)

topic ──► DISCOVER (GitHub search, multi-query)          src/fable/discover.py
              │
              ▼
        SNAPSHOT (repo, contributors, commits, releases) src/fable/github.py, store.py
              │   everything timestamped — we care about change, not state
              ▼
        SIGNALS (deterministic metrics, no LLM)          src/fable/signals.py
              │   velocity, acceleration, bus factor, breadth, cadence, momentum
              ▼
        SCORES (0–100, normalized within cohort)         src/fable/scoring.py
              │
              ▼
        REPORT (markdown, every claim ← a signal)        src/fable/report.py

Two design rules are enforced from day one:

1. Evidence-binding — every statement in a report traces to a computed signal. Phase 1 is fully deterministic (no LLM), so this is true by construction; when the LLM analyst layer arrives (Phase 2), a mechanical validator keeps it true.
2. Structural signals over vanity metrics — bus factor, contributor breadth, and rate-of-change are weighted over raw stars.

Where this is going

Phase	Deliverable	Status
1	Technology intelligence reports (deterministic)	✅ working
2	AI analyst layer — natural-language Q&A, memos, committee	next
3	Forecasting — falsifiable predictions, self-graded scoreboard	planned
4	Opportunity engine — white-space detection	planned
5	Decision platform	planned

Full plan: docs/ROADMAP.md · Vision: docs/VISION.md · Architecture: docs/ARCHITECTURE.md

For contributors (human or AI)

This repo is built to be resumable cold — by a contributor, or by an AI agent in a fresh session:

• HANDOFF.md — exact current state + what to do next. Start here.
• docs/CONTEXT.md — the full origin story and thinking behind the project.
• docs/DECISIONS.md — every significant decision, with reasoning.
• CHANGELOG.md — every change, as it happened.

License

MIT — as open as it gets.