Metadata-Version: 2.4
Name: oneport-context
Version: 0.3.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. 0-BYOK: runs on OnePort's managed models, metered to your account.
Author: OnePort Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/oneport-debug/oneport-context
Project-URL: Repository, https://github.com/oneport-debug/oneport-context
Keywords: code-explanation,onboarding,documentation,codebase,walkthrough,lsp,notebooklm,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Documentation
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: oneport-debug-core>=0.1.0
Requires-Dist: oneport-account>=0.1.0
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.8.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: PyYAML>=6.0.2
Provides-Extra: lsp
Requires-Dist: pygls>=1.3.0; extra == "lsp"
Provides-Extra: video
Requires-Dist: pillow>=10.0.0; extra == "video"
Requires-Dist: moviepy>=2.0.0; extra == "video"
Requires-Dist: gTTS>=2.5.0; extra == "video"
Requires-Dist: pyttsx3>=2.90; extra == "video"
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0.0; extra == "pdf"
Dynamic: license-file

# 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
onp account login <op_live_...>    # 0-BYOK: managed models, metered to your account
                                   # token: https://www.oneport.co.in/console

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 login it still works in **heuristic mode** (structure + docstrings) — free and
offline, just less prose.

### Keeping the index fresh

The index is cached in `.context/` so `show`/`video`/`pdf`/`chat` are instant — but a
cached index is a snapshot, and a stale snapshot drives a wrong tour. oneport-context
checks the cache against your repo as it is *now* and tells you when it has drifted:

```bash
oneport-context index ./my-repo --check   # "index is stale — 3 added, 1 modified"; exit 1 if stale
oneport-context show  ./my-repo --fresh   # rebuild before showing (any command takes --fresh)
```

`show`/`video`/`pdf`/`chat` print a clear warning when they're driven by a stale index,
rather than presenting it as current. `index --check` exits non-zero when stale, so you
can wire it into a pre-commit hook or CI.

### Tuning the scan

By default the walker skips the usual noise (`node_modules`, `.venv`, build output),
**respects your repo's `.gitignore`**, and caps at 4000 files. Override any of that in an
optional `.oneport-context.yml` at the repo root:

```yaml
scan:
  ignore: ["generated/**", "*.pb.go"]   # extra glob patterns to skip
  languages: {".astro": "Astro"}        # index extra extensions as a language
  max_files: 12000                      # raise the cap for a big monorepo
  respect_gitignore: true               # (default) honor .gitignore
```

If the file cap truncates the scan, that's surfaced — a partial index is never presented
as a complete one.

## Commands

| Command | What it does | Extra |
|---|---|---|
| `demo` | Zero-config narrated walkthrough of a bundled repo | — |
| `index ./repo` | Build the hierarchical understanding (cached); `--check` reports staleness | — |
| `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 when logged in (`oneport-account login`);
  heuristic mode works without it.
- Only structure travels to the model — file paths, symbol names, docstrings and the
  README, **never raw file contents**. Your code stays on your machine.

## License

Apache-2.0
