Explore Python repositories with semantic search and source-cited answers.
Import a public GitHub repository, browse its files and symbols, and ask how the code works. Every import and answer is tied to a specific commit, so you can follow citations back to the exact source lines.
- Search four ways — exact, lexical, semantic, or hybrid, with filters by file type and path.
- Follow the evidence — cited answers and repository overviews link to source ranges.
- Keep your context — revisit saved questions, export answers, and browse older snapshots after a refresh.
- Run locally — local embeddings, optional Groq generation, and background jobs that recover after a restart.
Built with React, TypeScript, FastAPI, and PostgreSQL with pgvector.
Requires Python 3.12, Node.js 22.12+, Docker Compose, and uv. Run commands from the repository root.
uv sync --locked --extra embeddings
npm ci --prefix frontend
cp -n .env.example .env # preserves an existing .envGenerate an owner token and set it as OWNER_TOKEN in .env:
python3 -c 'import secrets; print(secrets.token_urlsafe(32))'The default embedding provider downloads and runs a small model locally. Set EMBEDDING_PROVIDER=disabled for exact and lexical search without model downloads. Reimport repositories after changing embedding settings.
docker compose -p understory-local up -d database
uv run alembic upgrade head
uv run --extra embeddings understory-demoThe demo loads a synthetic repository so you can try the workspace before importing your own.
Run each command in a separate terminal:
uv run --extra embeddings understory-api
uv run --extra embeddings understory-worker
npm run dev --prefix frontendOpen 127.0.0.1:5173, choose Open Understory, and enter your owner token.
To import a real repository, add its owner/name to ALLOWED_REPOSITORIES in .env, restart the API and worker, and use Import repository. Start with a small public Python project; pallets/itsdangerous at tag 2.2.0 is a verified example.
Set these values in .env, then restart the API and worker:
GENERATION_PROVIDER=groq
GENERATION_MODEL=openai/gpt-oss-120b
GROQ_API_KEY=your_key_here
DAILY_TOKEN_BUDGET=50000Use a model available to your Groq account. Questions and selected source excerpts are sent to Groq; embeddings stay local and provider keys stay on the server. Search works without generation. The daily token budget is an application limit; provider quotas still apply.
With PostgreSQL running:
uv run ruff check backend migrations tests scripts
uv run pytest -q
npm run build --prefix frontendBackend tests use isolated database schemas and make no Groq calls. For browser tests, start the app and seed demo snapshot A, then run:
PLAYWRIGHT_BROWSERS_PATH="$PWD/.cache/playwright" npm exec --prefix frontend -- playwright install chromium
PLAYWRIGHT_BROWSERS_PATH="$PWD/.cache/playwright" npm test --prefix frontendThe API runs at http://127.0.0.1:8017 with interactive docs at /api-docs. Health checks are /v1/health and /v1/ready; PostgreSQL uses port 54329.
- Architecture — design decisions and tradeoffs.
- Technical specification — data model, jobs, and API contracts.
- Operations — recovery, model changes, retention, and backups.
- Evaluation and verification — methodology, results, and release checks.
- Scope — supported workflows and limits.
Understory is a local, single-owner MVP for small public Python repositories. It indexes Python, Markdown/RST, and selected text configs; excluded files remain visible in the inventory. Imported code is never executed. Hosted access, private repositories, and additional language parsers are outside the current scope. Citations identify the source used; review generated claims against it.
No project-wide license has been selected. See third-party notices for bundled dependencies and assets.
