Neural_Seed

Self-hosted AI deal discovery for solo operators — angels, scouts, and sector-focused VCs. Thesis-as-code, transparent scoring, zero data-provider lock-in.

⚠️ Security note: Neural_Seed has no authentication. Run on localhost only. Do not expose it to the public internet.

What it does

1. Ingests public signals (GitHub trending, Hacker News "Show HN", user-configured RSS feeds).
2. Extracts structured company + founder data with Claude (tool-use, temperature=0, prompt hashes stored).
3. Scores each company against a Markdown thesis you control (ships with theses/devinfra-v1.md; fork and write your own).
4. Surfaces a ranked pipeline in a small web UI + a daily top-3 brief to stdout (or SMTP).

Every score is traceable to the exact prompt bytes, model version, and source documents that produced it.

Quickstart — demo mode (no API keys)

git clone <repo-url> neural_seed
cd neural_seed
cp .env.example .env              # defaults are fine
make install                       # uv sync + alembic upgrade + tailwind build
make demo                          # seeds demo DB + starts the api

Open http://localhost:8000 — you'll see a fake pipeline populated from tests/fixtures/demo/.

Full mode (real data)

Edit .env and set:

NEURAL_SEED_DEMO=0
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...

Then:

docker compose up -d postgres
make install
make run

The in-process scheduler will start ingestion jobs on their cadence (GitHub trending daily, HN Show HN hourly).

Writing your own thesis

Theses live in theses/ as Markdown with a YAML front-matter block. Copy theses/devinfra-v1.md, rename it, edit the rubric, then:

export NEURAL_SEED_THESIS=my-thesis-v1
make run

Scores are keyed on thesis_version = {name}-{version}-{sha256(file)[:8]} — editing the thesis file automatically produces a new version, so history is preserved.

Architecture

See DESIGN.md for the full design — stack choices, data model, LLM contracts, migration strategy, and the milestone breakdown.

High-level:

Sources ──► Ingestion ──► Storage ──► Intelligence ──► Surface
(connectors)  (scheduler)  (Postgres)   (enrichment +   (api + ui +
                                         scoring)        briefs)

Stack: Python 3.12 + uv, FastAPI + Jinja + HTMX + Tailwind, Postgres 16 + pgvector, SQLAlchemy 2.0 async, Alembic, APScheduler (in-process), Claude via anthropic SDK, Voyage embeddings.

Commands

Task	Command
Install + migrate + build Tailwind	make install
Run full test suite (ruff + mypy + pytest)	make test
Run stack locally (real keys)	make run
Run in demo mode (no keys)	make demo
Seed fixture data	make seed
End-to-end smoke test	make smoke
Reset DB (destructive)	make clean

Contributing

See CONTRIBUTING.md.

License

Apache 2.0. See LICENSE.