# Using Speedi in Your App (Agent Guide)

Speedi is a typed, stateful, async-first CLI framework for Python. This guide shows how to embed Speedi into your application or agent.

## Install

Optional color extras:

```bash
# Base (local dev can run without install)
pip install -e .

# With rich colors
pip install -e .[rich]
```

## Define your CLI

```python
import speedi

app = speedi.App(name="myapp")

@app.command()
@speedi.validate_args
def login(user: str):
    """Log in a user"""
    speedi.session["user"] = user

@app.command()
@speedi.validate_args
def whoami() -> str:
    return speedi.session.get("user", "<anonymous>")

if __name__ == "__main__":
    app.run()
```

Run:

```bash
python -m myapp --help
python -m myapp --persist login alice
python -m myapp whoami
```

## Types and validation

- Use Python type hints for parameters. Speedi builds the parser from annotations.
- Supported today: `str`, `int`, `float`, `bool`, `Optional[T]`, `List[T]`.
- `@speedi.validate_args` performs lightweight runtime checks. Replace with Satya when available.

## Session and persistence

- Global session: `speedi.session` (dict-like).
- Persist after any mutating command by passing `--persist` or setting `SPEEDI_PERSIST=1`.
- Session file path: `~/.speedi/session.json` (override with `SPEEDI_SESSION_FILE`).

## Concurrency primitives

```python
from typing import List

@app.command()
@speedi.validate_args
async def fetch(urls: List[str], concurrency: int = 10):
    results = await speedi.parallel(download, urls, concurrency=concurrency)
    # do something with results
```

`parallel()` accepts async or sync functions and preserves order.

## Colored output

Use the built-in helpers for user-facing messages:

```python
speedi.info("Starting…")
speedi.success("Done!")
speedi.warning("Careful…")
speedi.error("Oops!")
```

Behavior:
- If `rich` is installed and color is enabled, outputs are styled.
- Otherwise, it gracefully falls back to plain `print`.
- Control with env `SPEEDI_COLOR=1|0` (default: enabled on TTY).

## Programmatic invocation (for agents/tests)

```python
app.invoke("login", "alice", persist=True)
app.invoke("whoami")  # prints alice
```

## Optional Rust core

- PyO3 crate scaffold under `rust/speedi_core/`.
- Python falls back if the native module is not present.

## Recommended patterns

- Keep command functions small and typed.
- Store auth/config in `speedi.session`.
- Return values for simple outputs; use `speedi.*` color helpers for status and logs.
- Use `--persist` only on commands that mutate state.

## Roadmap hooks (placeholders)

- JSON output mode (machine-readable).
- Autocomplete scripts for bash/zsh/fish.
- Plugin system (tools, shell, websearch) with entry points.
- Rust-based parser toggled via env/feature flag.
