# Speedi

A typed, stateful, high-performance CLI framework for Python.

- Declarative, Typer-like API
- Type-hint aware parsing and validation (Satya-ready stubs)
- Stateful session (in-memory, optional persistence)
- Async-first with simple parallel primitives
- Optional Rust core (PyO3) scaffold

## Quickstart (local, no install)

```bash
python examples/speedi_example.py --help
python examples/speedi_example.py greet Alice 30 --loud
```

Example output:

```
Hello Alice, age 30
HELLO ALICE
```

## Session (optional persistence)

```bash
python examples/speedi_example.py login alice
python examples/speedi_example.py whoami
```

To persist session between runs, pass `--persist` to commands that mutate session or set env `SPEEDI_PERSIST=1`.

Session file path (if persisted): `~/.speedi/session.json`

## Project Layout

- `speedi/` – core Python package
  - `app.py` – `App` and command system
  - `session.py` – session management
  - `concurrency.py` – `parallel` helper
  - `validation.py` – type validation stubs
  - `engine.py` – optional Rust bridge (stub)
  - `__init__.py` – exports
- `examples/` – example CLI
- `rust/speedi_core/` – optional Rust core (PyO3) scaffold
- `tests/` – minimal tests

## Rust core (optional)

A PyO3 stub is included under `rust/speedi_core`. It's not required to run the Python example.

## Colors

Speedi supports colored output via Rich with graceful fallback.

- Install extras: `pip install -e .[rich]`
- Auto-enabled on TTY; force with `SPEEDI_COLOR=1` or disable with `SPEEDI_COLOR=0`.
- Try: `python examples/speedi_example.py colors`

## Agent guide

See `AGENT.md` for integrating Speedi into your app/agent: commands, session, concurrency, and color helpers.

## License

MIT
