Metadata-Version: 2.4
Name: agentos-nano
Version: 1.0.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
Provides-Extra: postgres
Requires-Dist: psycopg-pool>=3.2.0; extra == 'postgres'
Requires-Dist: psycopg[binary]>=3.2.0; extra == 'postgres'
Description-Content-Type: text/markdown

# AgentOS Nano

AgentOS Nano is a lightweight Python runtime for building durable AI-agent workflows from a
small YAML DSL. It focuses on the runtime problems that show up once an agent moves beyond a
demo: retries, crash recovery, replay, auditability, tenant isolation, approval gates,
compensation, and safe workflow evolution.

The project ships with an `agentos` CLI, local example workflows, and reusable Python modules for
embedding workflow execution into your own product.

> Status: beta. AgentOS Nano is suitable for local prototypes, demos, and early integration work.
> Regulated production use still requires deployment-level controls, legal review, key management,
> operational monitoring, and organization-specific compliance validation.

## Highlights

- YAML workflow DSL with functions, tools, retries, timeouts, schemas, conditions, and parallel groups.
- Durable event-sourced execution with SQLite and Postgres-compatible event stores.
- Crash-resilient replay and resume with deterministic workflow state reconstruction.
- Input and output JSON Schema validation for safer step contracts.
- Multi-tenant event partitioning through `tenant_id`.
- HMAC audit-chain verification for tamper-evident event logs.
- Security-aware CLI rendering with sensitive-field redaction.
- Human approval gates for support and operations workflows.
- Step compensation and reconciliation helpers for finance-like workflows.
- Healthcare hardening primitives for PII detection, redaction, and encrypted payload envelopes.
- Experiment tracking helpers for AI research workflows.
- Workflow versioning and rollback primitives.
- Multi-LLM routing metadata for per-step model/provider selection.
- Visual workflow graph export plus Airflow and Dagster orchestration specs.
- OpenTelemetry-compatible metrics hooks with an in-memory fallback.

## Installation

Install from PyPI:

```powershell
pip install agentos-nano
```

Or install from a local checkout:

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

Requirements:

- Python 3.10 or newer
- `uv` for the recommended development workflow

An OpenAI API key is only required for commands or integrations that call an LLM provider. The
bundled example workflows run locally without external credentials.

## Quickstart

Run the example data pipeline:

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

Run the crash-recovery demo:

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

Replay a workflow execution:

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

Export a replay trace as JSON:

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

Inspect runtime configuration:

```powershell
uv run agentos config
```

## Workflow DSL

Workflows are defined in YAML. A minimal workflow looks like this:

```yaml
name: Support Triage
model: gpt-4o-mini
steps:
  - id: classify
    function: agentos_nano.handlers:search
    args:
      topic: "refund request"
    timeout: 10
    output_schema:
      type: object

  - id: route
    if:
      step: classify
      exists: true
    then: reply
    else: escalate

  - id: reply
    function: agentos_nano.handlers:save
    approval:
      id: support-lead
      decision: approved

  - id: escalate
    function: agentos_nano.handlers:transform
```

Supported step fields include:

- `function`: Python callable path in `module:function` form.
- `tool`: Tool name resolved from the runtime tool registry.
- `args`: Arguments passed into the function or tool.
- `retries`: Number of retries after the first attempt.
- `timeout`: Step timeout in seconds.
- `input_schema` and `output_schema`: JSON Schema validation.
- `parallel`: Adjacent steps with the same group name run concurrently.
- `if`, `then`, `else`: Conditional routing.
- `approval`: Human approval gate metadata.
- `compensation`: Python callable path used if a later step fails.
- `model` and `provider`: Per-step LLM routing metadata.
- `experiment`: Experiment identifier for research workflows.

## CLI Reference

```powershell
uv run agentos --help
uv run agentos --version
uv run agentos run examples/data_pipeline.yaml --db agentos.db
uv run agentos demo examples/data_pipeline.yaml --crash-at-step 2 --db demo.db
uv run agentos replay <workflow-id> --db demo.db
uv run agentos retention
uv run agentos retention --days 30 --apply
```

Useful display options:

- `--verbosity quiet`
- `--verbosity normal`
- `--verbosity debug`
- `--tenant-id <tenant>`

## Python Usage

Run a workflow directly from Python:

```python
from pathlib import Path

from agentos_nano.event_store import SQLiteEventStore
from agentos_nano.runtime import load_runnable_workflow
from agentos_nano.workflow import resume_workflow

loaded = load_runnable_workflow(Path("examples/data_pipeline.yaml"))

with SQLiteEventStore("agentos.db") as store:
    result = resume_workflow(
        store,
        "workflow-123",
        loaded.steps,
        tool_registry=loaded.tool_registry,
        tenant_id="default",
    )

print(result.state.status)
```

Use domain primitives:

```python
from agentos_nano.finance import reconcile_amounts
from agentos_nano.healthcare import detect_pii, redact_pii

findings = detect_pii("Patient email is ada@example.test")
safe_payload = redact_pii({"email": "ada@example.test"})
report = reconcile_amounts({"cash": "10.00"}, {"cash": "9.50"})
```

## IAM Cybersecurity Use Case

AgentOS Nano can act as a single durable control plane for identity and access management workflows.
An IAM team can model access requests, risk scoring, human approvals, provisioning,
reconciliation, compensation, audit evidence, and replay from one workflow definition.

Example: high-risk production access request.

```yaml
name: IAM Access Review
steps:
  - id: ingest_identity_request
    function: agentos_nano.handlers:ingest_identity_request
    args:
      user: ada.lovelace
      department: Engineering
      requested_role: Production Admin
      resource: payments-production
      justification: Emergency incident response

  - id: evaluate_access_risk
    function: agentos_nano.handlers:evaluate_access_risk

  - id: provision_access
    function: agentos_nano.handlers:provision_access
    approval:
      id: security-manager
      decision: approved
    compensation: agentos_nano.handlers:revoke_access

  - id: reconcile_access
    function: agentos_nano.handlers:reconcile_access
```

Run it locally:

```powershell
uv run agentos run examples/iam_access_review.yaml --db iam-demo.db --tenant-id acme-security
uv run agentos replay <workflow-id> --db iam-demo.db --tenant-id acme-security
```

How AgentOS Nano helps IAM teams:

- **Access request intake**: normalize user, role, resource, and justification data.
- **Risk scoring**: classify privileged, production, emergency, or break-glass access.
- **Approval gates**: pause or route sensitive actions through a human reviewer.
- **Provisioning execution**: run deterministic local or external provisioning handlers.
- **Compensation**: revoke access automatically if later workflow steps fail.
- **Reconciliation**: compare requested, approved, and provisioned state.
- **Tenant isolation**: partition workflow evidence by customer, business unit, or environment.
- **Audit trail**: preserve event-sourced history with HMAC chain verification.
- **Replay**: reconstruct exactly what happened during an access review.
- **Retention**: prune old workflow histories using explicit retention policy.
- **Metrics**: emit workflow counters and durations for operational monitoring.
- **Orchestration export**: represent the workflow for Airflow or Dagster integration.

This makes AgentOS Nano useful for IAM scenarios such as privileged access requests, access
certification campaigns, emergency access workflows, joiner-mover-leaver automation, entitlement
cleanup, and post-incident access evidence collection.

## Event Store And Replay

AgentOS Nano persists workflow execution as immutable events. The runtime can reconstruct state by
replaying those events in order.

Current capabilities:

- SQLite event store for local durable execution.
- Postgres-compatible event store API.
- HMAC chain verification for event integrity.
- Tenant-aware reads and writes.
- Workflow retention preview and pruning.
- Replay rendering and JSON export.

## Security And Compliance Notes

AgentOS Nano includes security-oriented primitives, but it is not a compliance certification by
itself.

Built-in controls include:

- CLI and replay redaction for common sensitive fields.
- PII detection and redaction helpers.
- Authenticated encrypted payload envelopes.
- HMAC audit-chain verification.
- Tenant partitioning in persisted events.
- Manual retention controls.
- Bandit security checks in the development workflow.

For operational details, see [docs/security.md](docs/security.md).

## Examples

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

Example handlers live in [src/agentos_nano/handlers.py](src/agentos_nano/handlers.py).

## Development

Install dependencies:

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

Run checks:

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

The repository currently enforces 100 percent test coverage.

## Packaging

Build distributions:

```powershell
python scripts/write_build_metadata.py
uv build
```

`scripts/write_build_metadata.py` stamps `src/agentos_nano/_build.py` with the current git commit,
short commit, UTC build time, package version, and dirty-tree flag before the wheel and sdist are
created. Keep the public PyPI version PEP 440 compliant, for example `1.0.0`, and use build
metadata for traceability. Release builds should run from a clean git tree; if not, `dirty: True`
is embedded intentionally.

Inspect the installed build:

```powershell
agentos version --build
```

Validate metadata:

```powershell
python -m twine check dist\agentos_nano-1.0.0*
```

Install the built wheel locally:

```powershell
pip install dist\agentos_nano-1.0.0-py3-none-any.whl
```

The build configuration excludes local `.env*` files, SQLite databases, caches, virtual
environments, and previous build artifacts from distributions.

## Project Structure

```text
src/agentos_nano/
  cli.py             CLI commands
  workflow.py        workflow execution and resume engine
  event_store.py     SQLite/Postgres event stores
  replay.py          replay and trace export
  dsl.py             YAML DSL parsing and validation
  healthcare.py      PII and encrypted payload helpers
  finance.py         compensation and reconciliation helpers
  support.py         approval gate primitives
  research.py        experiment tracking helpers
  versioning.py      workflow version registry
  routing.py         multi-LLM routing primitives
  visual.py          visual workflow graph export
  orchestration.py   Airflow/Dagster specs
```

## Roadmap

- Richer CLI commands for approval queues, version management, and graph export.
- Production-grade key management integrations.
- First-class Postgres integration tests.
- Optional OpenTelemetry exporter configuration.
- UI package for visual workflow authoring.
- Deeper Airflow and Dagster runtime adapters.

## License

No license file is currently included in this repository. Add a `LICENSE` file before distributing
or accepting external contributions under an open-source license.
