Metadata-Version: 2.4
Name: agentos-nano
Version: 0.2.0
Summary: A lightweight framework for building and deploying AI agents with minimal boilerplate code.
Project-URL: Homepage, https://github.com/jabbala10-bit/agentos-nano
Project-URL: Issues, https://github.com/jabbala10-bit/agentos-nano/issues
Project-URL: Source, https://github.com/jabbala10-bit/agentos-nano
Author-email: AgentOS Labs <jabbala10@gmail.com>
Keywords: agents,ai,cli,llm,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: openai>=1.109.0
Requires-Dist: pydantic<3,>=2.10.6
Requires-Dist: python-dotenv<2,>=1.0.1
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=14.1.0
Requires-Dist: typer>=0.17.4
Description-Content-Type: text/markdown

# agentos-nano

`agentos-nano` is a small crash-resilient workflow runner for demonstrating the core AgentOS runtime.
Phase 1 focuses on a believable local demo: install the CLI, run a YAML workflow, simulate a crash,
resume automatically, and replay the trace.

## What Phase 1 Can Do

- Parse a simple YAML workflow DSL with line-aware validation errors.
- Execute local workflow steps from YAML with terminal status output.
- Simulate a runtime crash after a chosen completed step and resume cleanly.
- Replay any stored workflow execution to the terminal or JSON.
- Build and install as a Python package with an `agentos` CLI entry point.

## Requirements

- Python `3.10` or newer
- `uv` for the local developer flow

An OpenAI API key is only needed for the optional `ask` command. The Phase 1 workflow demo works
without external credentials.

Useful runtime overrides can live in `.env`:

```dotenv
AGENTOS_DEFAULT_DB=agentos.db
AGENTOS_DEMO_DB=demo.db
AGENTOS_DEMO_CRASH_STEP=3
AGENTOS_DEMO_RESTART_DELAY_SECONDS=1
AGENTOS_LOG_VERBOSITY=normal
AGENTOS_REDACTION_ENABLED=true
AGENTOS_SENSITIVE_FIELDS=api_key,authorization,cookie,cvv,email,password,phone,secret,session,ssn,token
# AGENTOS_EVENT_RETENTION_DAYS=30
```

By default, CLI output and replay traces redact common sensitive fields such as `api_key`,
`token`, `password`, `email`, and `phone`. Use `--verbosity quiet|normal|debug` on `run`,
`demo`, and `replay` to control how much execution detail is shown.

For the full Phase 2 behavior, including checkpoint display protection, persistence defaults,
and retention semantics, see [docs/security.md](docs/security.md).

## Quickstart

1. Install dependencies:

```powershell
uv sync --dev
```

2. Run the example workflow:

```powershell
uv run agentos run examples/data_pipeline.yaml --db demo.db
```

3. Run the crash demo:

```powershell
uv run agentos demo examples/data_pipeline.yaml --crash-at-step 2 --db demo.db
```

Expected outcome:

- the workflow runs until step 2 completes
- the process is intentionally killed
- the runtime restarts after 1 second
- execution resumes from step 3 with `0 steps repeated`

4. Replay the execution:

```powershell
uv run agentos replay demo-<workflow-id> --db demo.db
```

The `demo` command prints the generated workflow ID in the terminal panels and final summary. For a
full walkthrough, see [docs/quickstart.md](docs/quickstart.md).

## Example Workflows

- [examples/data_pipeline.yaml](examples/data_pipeline.yaml)
- [examples/research_agent.yaml](examples/research_agent.yaml)
- [examples/summarizer.yaml](examples/summarizer.yaml)
- [examples/support_triage.yaml](examples/support_triage.yaml)

These ship with simple local handlers in [src/agentos_nano/handlers.py](src/agentos_nano/handlers.py)
so the demo stays self-contained.

## CLI Commands

Show help:

```powershell
uv run agentos --help
```

Show version:

```powershell
uv run agentos --version
```

Run a workflow:

```powershell
uv run agentos run examples/data_pipeline.yaml --db agentos.db
```

Run the crash demo:

```powershell
uv run agentos demo examples/data_pipeline.yaml --crash-at-step 2 --db demo.db
```

Replay a workflow:

```powershell
uv run agentos replay <workflow-id> --db demo.db
```

Export replay JSON:

```powershell
uv run agentos replay <workflow-id> --db demo.db --json replay.json
```

Show current config for the optional LLM command path:

```powershell
uv run agentos config
```

Inspect or apply event retention:

```powershell
uv run agentos retention
uv run agentos retention --days 30 --apply
```

## Security Notes

- `run`, `demo`, and `replay` mask common sensitive fields by default
- `quiet`, `normal`, and `debug` change output detail, not the basic masking contract
- replay JSON export is policy-aware and masked by default
- retention is manual by default and prunes whole workflow histories by age

Operational details live in [docs/security.md](docs/security.md).

## Packaging

Build a distributable package:

```powershell
uv build
```

Install the built wheel into a fresh environment:

```powershell
python -m venv .venv-release
.venv-release\Scripts\python -m pip install dist\agentos_nano-0.1.0-py3-none-any.whl
.venv-release\Scripts\agentos --help
```

Package metadata lives in [pyproject.toml](pyproject.toml).

## Development Checks

```powershell
uv run ruff check .
uv run mypy
uv run pytest
uv run bandit -c pyproject.toml -r src
```

## Current Scope

Phase 1 is meant to be workable and demonstrable, not final-product complete. The strongest path
today is the local trust demo built around `run`, `demo`, and `replay`.
