Metadata-Version: 2.5
Name: orbit-dev
Version: 0.1.1
Summary: Offline-first coding companion that helps beginners understand and trust their Python code.
Project-URL: Homepage, https://github.com/itanand/Orbit
Project-URL: Documentation, https://itanand.github.io/Orbit/
Project-URL: Issues, https://github.com/itanand/Orbit/issues
Project-URL: Changelog, https://github.com/itanand/Orbit/blob/master/orbit-core/CHANGELOG.md
Author: Anand Mohan
License-Expression: MIT
License-File: LICENSE
Keywords: ai,ai-generated code,beginners,cli,debugging,education,error messages,ollama,security,students,traceback,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: psutil>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.15
Requires-Dist: watchfiles>=0.24
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.0; extra == 'anthropic'
Provides-Extra: check
Requires-Dist: ruff>=0.6; extra == 'check'
Provides-Extra: demo
Requires-Dist: pillow>=10; extra == 'demo'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pygls>=2.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: lsp
Requires-Dist: pygls>=2.0; extra == 'lsp'
Description-Content-Type: text/markdown

# Orbit

**Understand and trust your Python code, especially the code AI wrote for you.**

Orbit is a free, offline-first companion for people learning Python. It runs your code, explains
errors in plain words, shows how your variables change, and catches the mistakes AI assistants
make: invented packages, outdated APIs, leaked keys and security holes.

```
pip install orbit-dev
orbit examples        # small broken programs to practise on
```

If the terminal then says `orbit` isn't recognized, pip put the command in a folder that isn't
on your PATH. Fix it once, then open a new terminal:

```
python -m orbit_dev path --add      # Windows: py -m orbit_dev path --add
```

## Commands

| Command | What it does | Needs AI? |
|---|---|---|
| `orbit run app.py` | Runs your file. If it fails, explains the error in plain words, points at the line and offers a fix as a diff, applied only if you type `y` (with a backup). | No |
| `orbit watch app.py` | Re-runs your file every time you save, with time and memory limits. | No |
| `orbit trace app.py` | Shows how every variable changes, step by step. `--html` saves a page you can replay in the browser. | No |
| `orbit check` | Finds packages that don't exist (AI hallucinations), outdated APIs, keys in the code and security mistakes, ranked by severity. `--fix` reviews fixes one by one. | No (`--ai` adds an AI logic review) |
| `orbit doctor -- <command>` | Runs any command (`pip`, `python`, `git`, `npm`…) and explains why it failed. | No |
| `orbit doctor --env` | Checks your Python setup: PATH, virtual environments, pip, PowerShell, and more. | No |
| `orbit explain app.py --lines 10-25` | Explains code line by line, for beginners or experts. | Yes |
| `orbit examples` | Copies practice programs into `./orbit-examples`. | No |
| `orbit theme` | Chooses how Orbit looks: dark, light, high-contrast, or no-colour plain ASCII for screen readers. | No |
| `orbit game on` | Optional game mode: XP, ranks and badges for learning, shown with `orbit profile`, plus a daily `orbit challenge`. Off by default, stored only on your computer. | No |
| `orbit path` | Makes the `orbit` command work in every terminal (adds pip's folder to PATH, after asking). | No |
| `orbit lsp` | Orbit's language server, for the VS Code extension and other editors (needs the `lsp` extra). | No |

Run `orbit COMMAND --help` for examples, and `orbit --install-completion` for Tab completion.

## A quick taste

```python
# 02_age.py
age = input("How old are you? ")
print("Next year you will be", age + 1)
```

`orbit run 02_age.py` explains that `input()` always returns text, points at line 2, and offers:

```diff
-age = input("How old are you? ")
+age = int(input("How old are you? "))
Apply this fix to 02_age.py? [y/N]:
```

## Private by default

Everything except `orbit explain` and the optional AI features works without AI and without
internet. `orbit check` asks PyPI about package names only (never code); `--offline` turns that
off.

The AI features use a free local model through Ollama, so your code never leaves your computer.
`orbit ai status` tells you what to install. You can also use your own key:

```
pip install "orbit-dev[anthropic]"   # only needed for Anthropic
orbit ai use anthropic               # or: openai, gemini, none
```

Cloud providers receive only the code snippet being explained or fixed, never your whole project.

## Extras

| Install | Adds |
|---|---|
| `pip install "orbit-dev[check]"` | ruff, for more static checks in `orbit check` |
| `pip install "orbit-dev[anthropic]"` | the official Anthropic SDK, for `orbit ai use anthropic` |
| `pip install "orbit-dev[lsp]"` | pygls, for `orbit lsp` and the Orbit VS Code extension |

## Settings

```
orbit config show
orbit config set level expert        # shorter explanations
orbit config set run.timeout 60      # seconds; 0 = no limit
orbit config set run.memory_mb 2048  # 0 = no limit
```

Settings live in `~/.orbit/config.toml`.

## Safety

Orbit runs your code the same way `python app.py` would: it is **not** a sandbox. Don't run code
you don't trust. Orbit never changes a file without asking, and keeps a backup of every file it
fixes in `~/.orbit/backups`.

## License

MIT © 2026 Anand Mohan
