Metadata-Version: 2.4
Name: oneport-context
Version: 0.1.0
Summary: Code Contextualizer — point it at any repo (no upload) and get a narrated architecture walkthrough, a handbook, and hover-to-explain in your editor. Runs locally on your own key.
Project-URL: Homepage, https://github.com/oneport-debug/oneport-context
Project-URL: Repository, https://github.com/oneport-debug/oneport-context
Author: OnePort Contributors
License: Apache-2.0
License-File: LICENSE
Keywords: code-explanation,codebase,developer-tools,documentation,lsp,notebooklm,onboarding,walkthrough
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: oneport-debug-core>=0.1.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.8.0
Provides-Extra: lsp
Requires-Dist: pygls>=1.3.0; extra == 'lsp'
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0.0; extra == 'pdf'
Provides-Extra: video
Requires-Dist: gtts>=2.5.0; extra == 'video'
Requires-Dist: moviepy>=2.0.0; extra == 'video'
Requires-Dist: pillow>=10.0.0; extra == 'video'
Requires-Dist: pyttsx3>=2.90; extra == 'video'
Description-Content-Type: text/markdown

# oneport-context

**Code Contextualizer — NotebookLM for your codebase, that never leaves your machine.**

Point it at any repo (however large — no upload) and it builds a hierarchical
understanding locally, then turns it into a **narrated architecture walkthrough**, a
**narrated MP4 video**, a **PDF handbook**, a **chat** that knows your code, and
**hover-to-explain** in your editor. Runs on your own model key (Google Gemini free
tier) or fully local — your code never leaves the machine.

## Try it in 60 seconds (no setup)

```bash
pip install oneport-context
oneport-context demo
```

Opens a narrated, animated walkthrough of a bundled sample repo in your browser — no
API key needed.

## Use it on your own repo

```bash
export GEMINI_API_KEY=…            # free key at aistudio.google.com/apikey

oneport-context index ./my-repo    # build the understanding (cached in .context/)
oneport-context show  ./my-repo    # narrated walkthrough in the browser
oneport-context video ./my-repo    # narrated MP4 (>= 8 min)   -> needs [video]
oneport-context pdf   ./my-repo    # PDF handbook, opens in browser -> needs [pdf]
oneport-context chat  ./my-repo    # ask questions in the terminal
oneport-context lsp   ./my-repo    # editor hover-to-explain -> needs [lsp]
```

Without a key it still works in **heuristic mode** (structure + docstrings) — free and
offline, just less prose.

## Commands

| Command | What it does | Extra |
|---|---|---|
| `demo` | Zero-config narrated walkthrough of a bundled repo | — |
| `index ./repo` | Build the hierarchical understanding (cached) | — |
| `show ./repo` | Localhost narrated architecture walkthrough | — |
| `video ./repo` | Narrated MP4 (`--minutes`, `--voice`) | `[video]` |
| `pdf ./repo` | Styled PDF handbook, served in the browser | `[pdf]` |
| `chat ./repo` | Terminal Q&A grounded in your code | — |
| `lsp ./repo` | Hover-to-explain Language Server (VS Code / Neovim / JetBrains) | `[lsp]` |

## Install with the features you want

```bash
pip install 'oneport-context[video,pdf,lsp]'
```
- `[video]` — pillow, moviepy (ffmpeg), gTTS voice
- `[pdf]` — reportlab
- `[lsp]` — pygls

## Why CLI, not upload

Big repos don't fit an upload box. The CLI walks the tree locally and builds a
**file -> module -> repo** summary (module summaries are batched, so a large repo
costs only a handful of model calls). Everything is cached in `.context/`; your code
never leaves the machine.

## Notes

- `video`/`pdf`/`chat` produce their best output with `GEMINI_API_KEY` set; heuristic
  mode works without it.
- Prefer local/air-gapped? Set `ONEPORT_MODE=local` and run against Ollama.
- Have an Anthropic key? Set `ANTHROPIC_API_KEY` and it takes priority automatically.

## License

Apache-2.0
