Metadata-Version: 2.4
Name: aaax
Version: 0.2.1
Summary: PSI shell for inspecting, mounting, and serving application packages.
Author: Junyan Cheng
License-Expression: Apache-2.0
Project-URL: Homepage, https://aaax.one
Project-URL: Documentation, https://aaax.one
Project-URL: Repository, https://github.com/Productive-Superintelligence/aaax
Project-URL: Issues, https://github.com/Productive-Superintelligence/aaax/issues
Keywords: agents,agentic systems,strategy,fastapi,sssn,lllm,psihub
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic>=2.7
Requires-Dist: uvicorn>=0.30
Provides-Extra: integrations
Requires-Dist: lllm-core>=0.2.0; extra == "integrations"
Requires-Dist: psihub>=0.0.1; extra == "integrations"
Requires-Dist: sssn>=0.1.0; extra == "integrations"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.8; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: lllm-core>=0.2.0; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Requires-Dist: psihub>=0.0.1; extra == "dev"
Requires-Dist: pymdown-extensions>=10.8; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: sssn>=0.1.0; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

# AAAX

AAAX is the PSI shell for package-shaped agent systems.

Use it to inspect a PsiHub package, mount its tactics and channels, bind local
handlers, open a small FastAPI surface, and hand that surface to a human,
script, or coding agent. The feel is intentionally shell-like: name the package,
see the resources, run one command, and get a callable system.

```bash
$ aaax inspect packages/analyst-pack
analysis-pack: Demo analyst package.
package analysis-pack psi://demo/analysis-pack
tactic echo psi://demo/analysis-pack/tactics/echo
channel events psi://demo/analysis-pack/channels/events

$ aaax serve packages/analyst-pack --port 8400
Uvicorn running on http://127.0.0.1:8400
```

AAAX does not replace LLLM, SSSN, PsiHub, Codex, Claude Code, schedulers,
sandboxes, or deployment platforms. It is the thin shell where those pieces are
named, mounted, served, and handed off.

## Install

```bash
python -m pip install aaax
```

For a reproducible install:

```bash
python -m pip install aaax==0.2.1
```

For local PSI composition:

```bash
python -m pip install "aaax[integrations]" lllm-core sssn psihub
```

## Mount A PsiHub Package

If a folder contains `psi.toml`, AAAX can serve it directly:

```bash
aaax serve packages/analyst-pack --port 8400
```

AAAX reads the manifest and mounts:

- package metadata and card hints;
- schemas, tactics, services, runs, and config;
- SSSN channels and snapshots;
- docs, examples, and assets.

Python tactic entrypoints become `/tactics/{name}/run`. Channels are backed by a
local SSSN store and exposed through `/channels/{name}/events`. Services that
point at one tactic are invokable as resources.

```bash
curl -X POST http://127.0.0.1:8400/tactics/finance_baseline/run \
  -H 'content-type: application/json' \
  -d '{"input": {"records": []}, "context": {"request": "demo"}}'
```

Append and query channel events:

```bash
curl -X POST http://127.0.0.1:8400/channels/events/events \
  -H 'content-type: application/json' \
  -d '{"input": {"kind": "record", "payload": {"text": "hello"}}}'

curl http://127.0.0.1:8400/channels/events/events?limit=10
```

## Write A Shell Script

For larger systems, write a `strategy.py`. A strategy is the shell script: it
mounts packages, assigns local names, and optionally defines `/run`.

```python
from aaax import Strategy


def build_strategy() -> Strategy:
    shell = Strategy(
        "analyst-shell",
        description="Mount source channels and analyst tactics.",
    )
    shell.use_package("packages/source-channels", prefix="sources")
    shell.use_package("packages/analyst-tactics", prefix="analysts")

    @shell.runner
    def run(input_value, *, context=None):
        return {
            "input": input_value,
            "resources": [resource.ref for resource in shell.resources],
            "context": context or {},
        }

    return shell
```

```bash
aaax serve strategy.py --port 8400
```

## Surface

Useful endpoints:

- `GET /health`
- `GET /strategy`
- `GET /resources`
- `GET /packages`
- `GET /tactics`
- `POST /tactics/{name}/run`
- `GET /channels`
- `POST /channels/{name}/events`
- `GET /channels/{name}/events`
- `POST /run`
- `POST /resources/{name}/invoke`
