Metadata-Version: 2.4
Name: airawatos-aos
Version: 0.1.0a1
Summary: aos — the AirawatOS build SDK + CLI: author, check, test, deploy governed components & solutions
Author: AirawatOS
License: Apache-2.0
Project-URL: Homepage, https://airos.airawat.org
Project-URL: Documentation, https://airos.airawat.org/developer/build/quickstart/
Project-URL: Source, https://github.com/AirawatOS/components
Keywords: airawatos,sdk,cli,civic,governed-components
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6
Provides-Extra: geo
Requires-Dist: h3>=4; extra == "geo"

# aos — the Airawat build SDK (P1 prototype)

One authoring model for every component kind. Unifies the two runtimes that exist today
(in-process `HANDLERS` engines + headless `main()` drivers) behind a single `ctx` object
and decorators, so the developer writes logic while the SDK owns broker transport, the
`(result, err)` convention, `HANDLERS` assembly, and reads/writes tracking → derived meta.

```python
from aos import engine, ctx

@engine.verb("assess-effectiveness", implements="intelligence.assess_effectiveness@0.1.0")
def assess(body):
    decs = ctx.facts("governance.decision").where(lambda d: d.get("outcome") == "approved")
    ...
    return ctx.write(obj)          # obj | (result, err) | raise aos.Reject(...)

HANDLERS = engine.handlers()       # app_host finds this unchanged
```

## What P1 proves (see the design proposal + harness)
- **Behavioural equivalence** — `components/engines/effectiveness-engine-aos/` is a
  faithful rewrite of the hand-written `effectiveness-engine`; identical output on the
  same inputs (`improved / −88.7% / 7.003→0.79`).
- **Derived meta** — `aos.meta.derive()` produces `implements/verbs/reads/writes/scopes`
  from the code (the decorator + the schemas the SDK saw); `aos.meta.validate()` is the
  single canonical gate (`aos check`), replacing the ≥3 divergent parsers in the tree.
- **No plumbing** — no ctx-dict, no `(result,err)` boilerplate, no manual `HANDLERS`,
  no hand-written `reads`/`writes`/`scopes`.

## Run the equivalence + meta harness
```
python3 <repo>/.../harness_aos.py     # (prototype harness; prints the equivalence + derived meta)
```

## Status / not-yet-P1
- `Ctx.from_broker` (headless transport) is implemented but exercised only lightly;
  the equivalence harness drives the in-process `from_host` path.
- Typed spine sugar (`ctx.recommend/open_case/route_to/decide`) and the `aos` CLI
  (`new/check/test/deploy/publish`) are the next P1/P2 increments.
- Packaging/on-path delivery of `aos` to components at runtime is a P2 concern
  (vendor into the bundle, or put `_common` on the engine load path).
