aaax 0.2.0__tar.gz → 0.2.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aaax-0.2.2/MANIFEST.in +11 -0
- {aaax-0.2.0 → aaax-0.2.2}/PKG-INFO +20 -5
- {aaax-0.2.0 → aaax-0.2.2}/README.md +19 -4
- {aaax-0.2.0 → aaax-0.2.2}/aaax/__init__.py +1 -1
- {aaax-0.2.0 → aaax-0.2.2}/aaax/server.py +1 -1
- {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/PKG-INFO +20 -5
- aaax-0.2.2/aaax.egg-info/SOURCES.txt +57 -0
- aaax-0.2.2/assets/aaax-logo-text-black.png +0 -0
- aaax-0.2.2/assets/aaax-logo-text-white.png +0 -0
- aaax-0.2.2/docs/CNAME +1 -0
- aaax-0.2.2/docs/assets/aaax-logo-black.png +0 -0
- aaax-0.2.2/docs/assets/aaax-logo-text-black.png +0 -0
- aaax-0.2.2/docs/assets/aaax-logo-text-white.png +0 -0
- aaax-0.2.2/docs/assets/aaax-logo-white.png +0 -0
- aaax-0.2.2/docs/composition/channels-services.md +78 -0
- aaax-0.2.2/docs/composition/index.md +48 -0
- aaax-0.2.2/docs/composition/psihub-packages.md +68 -0
- aaax-0.2.2/docs/composition/strategy-resources.md +74 -0
- aaax-0.2.2/docs/concepts/launch-boundary.md +50 -0
- aaax-0.2.2/docs/concepts/package-composition.md +68 -0
- aaax-0.2.2/docs/concepts/strategies.md +73 -0
- aaax-0.2.2/docs/getting-started.md +126 -0
- aaax-0.2.2/docs/index.md +121 -0
- aaax-0.2.2/docs/javascripts/mermaid-init.20260629.js +286 -0
- aaax-0.2.2/docs/javascripts/vendor/mermaid-LICENSE.txt +21 -0
- aaax-0.2.2/docs/javascripts/vendor/mermaid.min.js +2029 -0
- aaax-0.2.2/docs/launch/agent-handoff.md +51 -0
- aaax-0.2.2/docs/launch/cli-shell.md +47 -0
- aaax-0.2.2/docs/launch/fastapi-surface.md +93 -0
- aaax-0.2.2/docs/launch/index.md +32 -0
- aaax-0.2.2/docs/overrides/partials/header.html +96 -0
- aaax-0.2.2/docs/overrides/partials/nav.html +64 -0
- aaax-0.2.2/docs/overrides/partials/source.html +10 -0
- aaax-0.2.2/docs/reference/cli.md +45 -0
- aaax-0.2.2/docs/reference/http-api.md +69 -0
- aaax-0.2.2/docs/reference/python-api.md +87 -0
- aaax-0.2.2/docs/stylesheets/custom.20260702.css +732 -0
- aaax-0.2.2/docs/tutorials/channel-events.md +58 -0
- aaax-0.2.2/docs/tutorials/compose-packages.md +67 -0
- aaax-0.2.2/docs/tutorials/serve-package.md +76 -0
- aaax-0.2.2/docs/tutorials/tactic-endpoint.md +49 -0
- aaax-0.2.2/mkdocs.yml +101 -0
- {aaax-0.2.0 → aaax-0.2.2}/pyproject.toml +1 -1
- {aaax-0.2.0 → aaax-0.2.2}/tests/test_docs_rendering.py +3 -3
- aaax-0.2.2/tests/test_sdist_contents.py +59 -0
- aaax-0.2.0/aaax.egg-info/SOURCES.txt +0 -20
- {aaax-0.2.0 → aaax-0.2.2}/LICENSE +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/__main__.py +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/cli.py +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/loader.py +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/models.py +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/packages.py +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/py.typed +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax/strategy.py +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/dependency_links.txt +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/entry_points.txt +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/requires.txt +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/top_level.txt +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/setup.cfg +0 -0
- {aaax-0.2.0 → aaax-0.2.2}/tests/test_strategy.py +0 -0
aaax-0.2.2/MANIFEST.in
ADDED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: aaax
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: PSI shell for inspecting, mounting, and serving application packages.
|
|
5
5
|
Author: Junyan Cheng
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -47,14 +47,23 @@ Requires-Dist: sssn>=0.1.0; extra == "dev"
|
|
|
47
47
|
Requires-Dist: twine>=5.1; extra == "dev"
|
|
48
48
|
Dynamic: license-file
|
|
49
49
|
|
|
50
|
-
# AAAX
|
|
50
|
+
# Advanced Autonomous Agent Executor (AAAX)
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
<p align="center">
|
|
53
|
+
<img src="assets/aaax-logo-text-black.png" alt="AAAX" width="420">
|
|
54
|
+
</p>
|
|
55
|
+
|
|
56
|
+
Advanced Autonomous Agent Executor (AAAX) is the PSI shell for package-shaped
|
|
57
|
+
agent systems.
|
|
53
58
|
|
|
54
59
|
Use it to inspect a PsiHub package, mount its tactics and channels, bind local
|
|
55
60
|
handlers, open a small FastAPI surface, and hand that surface to a human,
|
|
56
|
-
script, or
|
|
57
|
-
see the resources, run one command, and get a callable system.
|
|
61
|
+
script, coding agent, or another system. The feel is intentionally shell-like:
|
|
62
|
+
name the package, see the resources, run one command, and get a callable system.
|
|
63
|
+
|
|
64
|
+
AAAX can also stand alone. A `Strategy` can be just a Pydantic-modeled resource
|
|
65
|
+
table plus local handlers exposed through FastAPI. LLLM, SSSN, and PsiHub are
|
|
66
|
+
optional bridges when you want tactic, channel, and package behavior.
|
|
58
67
|
|
|
59
68
|
```bash
|
|
60
69
|
$ aaax inspect packages/analyst-pack
|
|
@@ -77,6 +86,12 @@ named, mounted, served, and handed off.
|
|
|
77
86
|
python -m pip install aaax
|
|
78
87
|
```
|
|
79
88
|
|
|
89
|
+
For a reproducible install:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
python -m pip install aaax==0.2.2
|
|
93
|
+
```
|
|
94
|
+
|
|
80
95
|
For local PSI composition:
|
|
81
96
|
|
|
82
97
|
```bash
|
|
@@ -1,11 +1,20 @@
|
|
|
1
|
-
# AAAX
|
|
1
|
+
# Advanced Autonomous Agent Executor (AAAX)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="assets/aaax-logo-text-black.png" alt="AAAX" width="420">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
Advanced Autonomous Agent Executor (AAAX) is the PSI shell for package-shaped
|
|
8
|
+
agent systems.
|
|
4
9
|
|
|
5
10
|
Use it to inspect a PsiHub package, mount its tactics and channels, bind local
|
|
6
11
|
handlers, open a small FastAPI surface, and hand that surface to a human,
|
|
7
|
-
script, or
|
|
8
|
-
see the resources, run one command, and get a callable system.
|
|
12
|
+
script, coding agent, or another system. The feel is intentionally shell-like:
|
|
13
|
+
name the package, see the resources, run one command, and get a callable system.
|
|
14
|
+
|
|
15
|
+
AAAX can also stand alone. A `Strategy` can be just a Pydantic-modeled resource
|
|
16
|
+
table plus local handlers exposed through FastAPI. LLLM, SSSN, and PsiHub are
|
|
17
|
+
optional bridges when you want tactic, channel, and package behavior.
|
|
9
18
|
|
|
10
19
|
```bash
|
|
11
20
|
$ aaax inspect packages/analyst-pack
|
|
@@ -28,6 +37,12 @@ named, mounted, served, and handed off.
|
|
|
28
37
|
python -m pip install aaax
|
|
29
38
|
```
|
|
30
39
|
|
|
40
|
+
For a reproducible install:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
python -m pip install aaax==0.2.2
|
|
44
|
+
```
|
|
45
|
+
|
|
31
46
|
For local PSI composition:
|
|
32
47
|
|
|
33
48
|
```bash
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: aaax
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: PSI shell for inspecting, mounting, and serving application packages.
|
|
5
5
|
Author: Junyan Cheng
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -47,14 +47,23 @@ Requires-Dist: sssn>=0.1.0; extra == "dev"
|
|
|
47
47
|
Requires-Dist: twine>=5.1; extra == "dev"
|
|
48
48
|
Dynamic: license-file
|
|
49
49
|
|
|
50
|
-
# AAAX
|
|
50
|
+
# Advanced Autonomous Agent Executor (AAAX)
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
<p align="center">
|
|
53
|
+
<img src="assets/aaax-logo-text-black.png" alt="AAAX" width="420">
|
|
54
|
+
</p>
|
|
55
|
+
|
|
56
|
+
Advanced Autonomous Agent Executor (AAAX) is the PSI shell for package-shaped
|
|
57
|
+
agent systems.
|
|
53
58
|
|
|
54
59
|
Use it to inspect a PsiHub package, mount its tactics and channels, bind local
|
|
55
60
|
handlers, open a small FastAPI surface, and hand that surface to a human,
|
|
56
|
-
script, or
|
|
57
|
-
see the resources, run one command, and get a callable system.
|
|
61
|
+
script, coding agent, or another system. The feel is intentionally shell-like:
|
|
62
|
+
name the package, see the resources, run one command, and get a callable system.
|
|
63
|
+
|
|
64
|
+
AAAX can also stand alone. A `Strategy` can be just a Pydantic-modeled resource
|
|
65
|
+
table plus local handlers exposed through FastAPI. LLLM, SSSN, and PsiHub are
|
|
66
|
+
optional bridges when you want tactic, channel, and package behavior.
|
|
58
67
|
|
|
59
68
|
```bash
|
|
60
69
|
$ aaax inspect packages/analyst-pack
|
|
@@ -77,6 +86,12 @@ named, mounted, served, and handed off.
|
|
|
77
86
|
python -m pip install aaax
|
|
78
87
|
```
|
|
79
88
|
|
|
89
|
+
For a reproducible install:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
python -m pip install aaax==0.2.2
|
|
93
|
+
```
|
|
94
|
+
|
|
80
95
|
For local PSI composition:
|
|
81
96
|
|
|
82
97
|
```bash
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
MANIFEST.in
|
|
3
|
+
README.md
|
|
4
|
+
mkdocs.yml
|
|
5
|
+
pyproject.toml
|
|
6
|
+
aaax/__init__.py
|
|
7
|
+
aaax/__main__.py
|
|
8
|
+
aaax/cli.py
|
|
9
|
+
aaax/loader.py
|
|
10
|
+
aaax/models.py
|
|
11
|
+
aaax/packages.py
|
|
12
|
+
aaax/py.typed
|
|
13
|
+
aaax/server.py
|
|
14
|
+
aaax/strategy.py
|
|
15
|
+
aaax.egg-info/PKG-INFO
|
|
16
|
+
aaax.egg-info/SOURCES.txt
|
|
17
|
+
aaax.egg-info/dependency_links.txt
|
|
18
|
+
aaax.egg-info/entry_points.txt
|
|
19
|
+
aaax.egg-info/requires.txt
|
|
20
|
+
aaax.egg-info/top_level.txt
|
|
21
|
+
assets/aaax-logo-text-black.png
|
|
22
|
+
assets/aaax-logo-text-white.png
|
|
23
|
+
docs/CNAME
|
|
24
|
+
docs/getting-started.md
|
|
25
|
+
docs/index.md
|
|
26
|
+
docs/assets/aaax-logo-black.png
|
|
27
|
+
docs/assets/aaax-logo-text-black.png
|
|
28
|
+
docs/assets/aaax-logo-text-white.png
|
|
29
|
+
docs/assets/aaax-logo-white.png
|
|
30
|
+
docs/composition/channels-services.md
|
|
31
|
+
docs/composition/index.md
|
|
32
|
+
docs/composition/psihub-packages.md
|
|
33
|
+
docs/composition/strategy-resources.md
|
|
34
|
+
docs/concepts/launch-boundary.md
|
|
35
|
+
docs/concepts/package-composition.md
|
|
36
|
+
docs/concepts/strategies.md
|
|
37
|
+
docs/javascripts/mermaid-init.20260629.js
|
|
38
|
+
docs/javascripts/vendor/mermaid-LICENSE.txt
|
|
39
|
+
docs/javascripts/vendor/mermaid.min.js
|
|
40
|
+
docs/launch/agent-handoff.md
|
|
41
|
+
docs/launch/cli-shell.md
|
|
42
|
+
docs/launch/fastapi-surface.md
|
|
43
|
+
docs/launch/index.md
|
|
44
|
+
docs/overrides/partials/header.html
|
|
45
|
+
docs/overrides/partials/nav.html
|
|
46
|
+
docs/overrides/partials/source.html
|
|
47
|
+
docs/reference/cli.md
|
|
48
|
+
docs/reference/http-api.md
|
|
49
|
+
docs/reference/python-api.md
|
|
50
|
+
docs/stylesheets/custom.20260702.css
|
|
51
|
+
docs/tutorials/channel-events.md
|
|
52
|
+
docs/tutorials/compose-packages.md
|
|
53
|
+
docs/tutorials/serve-package.md
|
|
54
|
+
docs/tutorials/tactic-endpoint.md
|
|
55
|
+
tests/test_docs_rendering.py
|
|
56
|
+
tests/test_sdist_contents.py
|
|
57
|
+
tests/test_strategy.py
|
|
Binary file
|
|
Binary file
|
aaax-0.2.2/docs/CNAME
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
aaax.one
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Channels And Services
|
|
2
|
+
|
|
3
|
+
AAAX makes channels and services available through the same shell boundary as
|
|
4
|
+
tactics. This lets a mounted package expose both "do work" and "share state"
|
|
5
|
+
operations without inventing a separate API surface.
|
|
6
|
+
|
|
7
|
+
## Channels
|
|
8
|
+
|
|
9
|
+
A package channel:
|
|
10
|
+
|
|
11
|
+
```toml
|
|
12
|
+
[channels.events]
|
|
13
|
+
form = "log"
|
|
14
|
+
description = "Application event stream."
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
becomes:
|
|
18
|
+
|
|
19
|
+
- a `channel` resource in `/resources`;
|
|
20
|
+
- an item in `/channels`;
|
|
21
|
+
- a local SSSN channel in the bound store;
|
|
22
|
+
- an append/query HTTP endpoint.
|
|
23
|
+
|
|
24
|
+
Append:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
curl -X POST http://127.0.0.1:8400/channels/events/events \
|
|
28
|
+
-H 'content-type: application/json' \
|
|
29
|
+
-d '{"input": {"kind": "record", "payload": {"id": "a1"}}}'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Query:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
curl 'http://127.0.0.1:8400/channels/events/events?after_cursor=0&limit=100'
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Channel Operations
|
|
39
|
+
|
|
40
|
+
The generic resource invocation path also supports channel operations:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
curl -X POST http://127.0.0.1:8400/resources/events/invoke \
|
|
44
|
+
-H 'content-type: application/json' \
|
|
45
|
+
-d '{"input": {"op": "info"}}'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Supported operations are:
|
|
49
|
+
|
|
50
|
+
- `info`
|
|
51
|
+
- `append`
|
|
52
|
+
- `query`
|
|
53
|
+
|
|
54
|
+
The HTTP convenience endpoints set `op` for you.
|
|
55
|
+
|
|
56
|
+
## Services
|
|
57
|
+
|
|
58
|
+
A service can point at a single tactic:
|
|
59
|
+
|
|
60
|
+
```toml
|
|
61
|
+
[services.api]
|
|
62
|
+
tactic = "echo"
|
|
63
|
+
transport = "fastapi"
|
|
64
|
+
description = "HTTP-facing echo service."
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
AAAX imports it as a `service` resource. If the tactic is locally bound, the
|
|
68
|
+
service resource uses the same handler:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
curl -X POST http://127.0.0.1:8400/resources/api/invoke \
|
|
72
|
+
-H 'content-type: application/json' \
|
|
73
|
+
-d '{"input": {"text": "hello"}}'
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
This is intentionally conservative. AAAX does not launch arbitrary service
|
|
77
|
+
processes from a manifest. It exposes the shell-facing resource boundary and
|
|
78
|
+
lets deployment or agent tooling decide how far to go.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Strategy
|
|
2
|
+
|
|
3
|
+
Strategy is the main reason AAAX exists. A strategy can stand alone as a
|
|
4
|
+
Pydantic-modeled resource table with local handlers. When you want more of the
|
|
5
|
+
PSI stack, LLLM owns tactic boundaries, SSSN owns channels and stores, and
|
|
6
|
+
PsiHub owns package manifests. AAAX gathers those resources into one shell and
|
|
7
|
+
exposes them as one command surface.
|
|
8
|
+
|
|
9
|
+
<div class="psi-flow">
|
|
10
|
+
<div><strong>Describe</strong><br />Write `psi.toml` resources.</div>
|
|
11
|
+
<div><strong>Mount</strong><br />Load the package into a shell.</div>
|
|
12
|
+
<div><strong>Bind</strong><br />Attach local tactic and channel handlers.</div>
|
|
13
|
+
<div><strong>Serve</strong><br />Expose the shell as Pydantic/FastAPI.</div>
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
## Resource Kinds
|
|
17
|
+
|
|
18
|
+
AAAX understands the package-facing resource kinds used by the PSI stack:
|
|
19
|
+
|
|
20
|
+
- package
|
|
21
|
+
- schema
|
|
22
|
+
- tactic
|
|
23
|
+
- channel
|
|
24
|
+
- snapshot
|
|
25
|
+
- service
|
|
26
|
+
- run
|
|
27
|
+
- config
|
|
28
|
+
- doc
|
|
29
|
+
- example
|
|
30
|
+
- asset
|
|
31
|
+
- custom
|
|
32
|
+
|
|
33
|
+
The built-in package bridge imports all of the PsiHub manifest sections that
|
|
34
|
+
matter for launch context, not only executable tactics.
|
|
35
|
+
|
|
36
|
+
## Strategy Rules
|
|
37
|
+
|
|
38
|
+
- Local names must be path-segment friendly.
|
|
39
|
+
- Prefix imported packages when names might collide.
|
|
40
|
+
- Keep original `psi://` refs in resource records.
|
|
41
|
+
- Treat channels as resources with shell-facing handlers, not hidden runtime state.
|
|
42
|
+
- Treat docs, examples, assets, package cards, and config as first-class context.
|
|
43
|
+
|
|
44
|
+
## Next
|
|
45
|
+
|
|
46
|
+
- See the exact resource record in [Strategy Resources](strategy-resources.md).
|
|
47
|
+
- Learn manifest import behavior in [PsiHub Packages](psihub-packages.md).
|
|
48
|
+
- Learn channel and service binding in [Channels And Services](channels-services.md).
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# PsiHub Packages
|
|
2
|
+
|
|
3
|
+
AAAX can mount a package folder or a direct `psi.toml` file:
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
from aaax import load_strategy
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
shell = load_strategy("packages/analyst-pack")
|
|
10
|
+
shell = load_strategy("packages/analyst-pack/psi.toml")
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The loader recognizes a package after it checks for `strategy.py` and `aaax.py`
|
|
14
|
+
in a directory. That keeps explicit strategy files in control when both exist.
|
|
15
|
+
|
|
16
|
+
## Imported Manifest Sections
|
|
17
|
+
|
|
18
|
+
AAAX imports:
|
|
19
|
+
|
|
20
|
+
- `[package]` as a package resource and shell metadata.
|
|
21
|
+
- `[card]` into package and strategy metadata.
|
|
22
|
+
- `[config]` as `config.default`.
|
|
23
|
+
- `[schemas.*]` as schema resources.
|
|
24
|
+
- `[tactics.*]` as tactic resources and local handlers when bound.
|
|
25
|
+
- `[channels.*]` as channel resources and local SSSN handlers when bound.
|
|
26
|
+
- `[snapshots.*]` as snapshot resources.
|
|
27
|
+
- `[services.*]` as service resources.
|
|
28
|
+
- `[runs.*]` as run resources.
|
|
29
|
+
- `[docs.*]`, `[examples.*]`, and `[assets.*]` as context resources.
|
|
30
|
+
|
|
31
|
+
## Tactic Entrypoints
|
|
32
|
+
|
|
33
|
+
AAAX imports the Python value named by `entry`:
|
|
34
|
+
|
|
35
|
+
```toml
|
|
36
|
+
[tactics.echo]
|
|
37
|
+
entry = "demo.tactics:echo"
|
|
38
|
+
runtime = "python"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
It supports:
|
|
42
|
+
|
|
43
|
+
- LLLM `Tactic` subclasses;
|
|
44
|
+
- LLLM `Tactic` instances;
|
|
45
|
+
- normal Python callables;
|
|
46
|
+
- zero-argument factories that return one of the above;
|
|
47
|
+
- objects with a `run` method.
|
|
48
|
+
|
|
49
|
+
When LLLM is installed, normal callables and `run` methods are wrapped through
|
|
50
|
+
`as_tactic`, so callers meet the same `CallContext` and validation boundary.
|
|
51
|
+
|
|
52
|
+
## Channel Stores
|
|
53
|
+
|
|
54
|
+
When a package has channels and `bind=True`, AAAX creates a local SSSN store:
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
shell.use_package("packages/source", store=".aaax/source-store")
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
If no store path is provided, the package folder gets a `.sssn` store. Existing
|
|
61
|
+
channels are reused.
|
|
62
|
+
|
|
63
|
+
## Package Cards
|
|
64
|
+
|
|
65
|
+
Cards are not execution code, but they matter. AAAX preserves card summaries,
|
|
66
|
+
tags, safety notes, latency notes, suggested commands, and metadata so future
|
|
67
|
+
agent handoff surfaces can inject useful package context without re-parsing the
|
|
68
|
+
manifest.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Strategy Resources
|
|
2
|
+
|
|
3
|
+
`StrategyResource` is the public record for one mounted resource:
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
from aaax import StrategyResource
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
resource = StrategyResource(
|
|
10
|
+
kind="tactic",
|
|
11
|
+
name="review",
|
|
12
|
+
ref="psi://demo/analyst-pack/tactics/review",
|
|
13
|
+
entrypoint="demo.tactics:review",
|
|
14
|
+
description="Review one record batch.",
|
|
15
|
+
metadata={"runtime": "python"},
|
|
16
|
+
)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Fields
|
|
20
|
+
|
|
21
|
+
`kind`
|
|
22
|
+
: The resource category. Built-in values are `tactic`, `channel`, `service`,
|
|
23
|
+
`schema`, `package`, `run`, `config`, `doc`, `example`, `snapshot`, `asset`,
|
|
24
|
+
and `custom`.
|
|
25
|
+
|
|
26
|
+
`name`
|
|
27
|
+
: The local name used in the shell and HTTP paths.
|
|
28
|
+
|
|
29
|
+
`ref`
|
|
30
|
+
: The stable package or service ref. Package imports preserve `psi://` refs.
|
|
31
|
+
|
|
32
|
+
`entrypoint`
|
|
33
|
+
: Optional Python import path. Tactics use this to bind local handlers.
|
|
34
|
+
|
|
35
|
+
`description`
|
|
36
|
+
: Short human-readable description.
|
|
37
|
+
|
|
38
|
+
`metadata`
|
|
39
|
+
: Structured hints copied from package resources, such as runtime, schema refs,
|
|
40
|
+
examples, config defaults, service transport, package version, or package card.
|
|
41
|
+
|
|
42
|
+
## Local Name Versus Ref
|
|
43
|
+
|
|
44
|
+
The same package resource can have different local names in different shells:
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
shell.use_package("packages/review", prefix="analysts")
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The tactic named `review` in the package becomes `analysts.review` locally, but
|
|
51
|
+
its ref remains:
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
psi://demo/review/tactics/review
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
This lets a shell compose multiple packages without rewriting their package
|
|
58
|
+
identity.
|
|
59
|
+
|
|
60
|
+
## Handler Binding
|
|
61
|
+
|
|
62
|
+
Resources are metadata by default. They become executable when AAAX stores a
|
|
63
|
+
handler under the same local name:
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
strategy.tactic(
|
|
67
|
+
"echo",
|
|
68
|
+
ref="psi://demo/tools/tactics/echo",
|
|
69
|
+
handler=lambda input_value, context=None: {"echo": input_value},
|
|
70
|
+
)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Handlers may be synchronous or asynchronous. If they accept a `context` keyword,
|
|
74
|
+
AAAX passes the request context.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Shell Boundary
|
|
2
|
+
|
|
3
|
+
AAAX is the shell between package metadata and a usable command surface. It
|
|
4
|
+
prepares the environment a caller needs, but it does not try to become the
|
|
5
|
+
caller.
|
|
6
|
+
|
|
7
|
+
## What The Shell Does
|
|
8
|
+
|
|
9
|
+
In the current surface, the shell does five things:
|
|
10
|
+
|
|
11
|
+
- Load a strategy file or package manifest.
|
|
12
|
+
- List and name the resources that belong to the application.
|
|
13
|
+
- Bind local handlers where the package provides local Python entrypoints.
|
|
14
|
+
- Prepare channel storage for package channels.
|
|
15
|
+
- Expose a FastAPI app with stable endpoints.
|
|
16
|
+
|
|
17
|
+
The agent-facing layer can build on this later by reading the same resource map,
|
|
18
|
+
package cards, docs, examples, and service URLs.
|
|
19
|
+
|
|
20
|
+
## What AAAX Avoids
|
|
21
|
+
|
|
22
|
+
AAAX does not own:
|
|
23
|
+
|
|
24
|
+
- model provider configuration;
|
|
25
|
+
- prompt execution;
|
|
26
|
+
- tool permission policy;
|
|
27
|
+
- distributed scheduling;
|
|
28
|
+
- production deployment;
|
|
29
|
+
- package storage;
|
|
30
|
+
- long-term event retention.
|
|
31
|
+
|
|
32
|
+
Those jobs belong to LLLM runtimes, SSSN stores, PsiHub, deployment platforms,
|
|
33
|
+
and agent tools. AAAX keeps the shell boring enough that all of those systems
|
|
34
|
+
can meet there.
|
|
35
|
+
|
|
36
|
+
## Handoff Shape
|
|
37
|
+
|
|
38
|
+
```mermaid
|
|
39
|
+
flowchart LR
|
|
40
|
+
A["Package card"] --> E["Handoff context"]
|
|
41
|
+
B["Resource refs"] --> E
|
|
42
|
+
C["FastAPI endpoints"] --> E
|
|
43
|
+
D["Docs and examples"] --> E
|
|
44
|
+
E --> F["Human operator"]
|
|
45
|
+
E --> G["Coding agent"]
|
|
46
|
+
E --> H["Automation script"]
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The handoff is intentionally data-shaped: names, refs, docs, endpoints, and
|
|
50
|
+
examples. That keeps AAAX compatible with many agent and IDE surfaces.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Package Composition
|
|
2
|
+
|
|
3
|
+
AAAX composes packages by mounting manifest resources into a shell. A package
|
|
4
|
+
remains the unit of publication and discovery. A strategy is the shell session
|
|
5
|
+
that chooses local names, binds handlers, and serves endpoints.
|
|
6
|
+
|
|
7
|
+
Package composition is optional. You can use AAAX with a hand-written strategy,
|
|
8
|
+
with one package, with several packages, or with only the LLLM/SSSN pieces that
|
|
9
|
+
the shell actually needs.
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart TD
|
|
13
|
+
A["psi.toml"] --> B["PsiHub manifest"]
|
|
14
|
+
B --> C["mounted resources"]
|
|
15
|
+
C --> D["Tactic handlers"]
|
|
16
|
+
C --> E["Channel handlers"]
|
|
17
|
+
C --> F["Docs, examples, assets"]
|
|
18
|
+
D --> G["FastAPI endpoints"]
|
|
19
|
+
E --> G
|
|
20
|
+
F --> H["Agent or human context"]
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Direct Package Shell
|
|
24
|
+
|
|
25
|
+
`strategy_from_package(path)` creates one shell from one package:
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from aaax import strategy_from_package
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
shell = strategy_from_package("packages/analyst-pack")
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The shell name defaults to `package.name`. Package card metadata is copied onto
|
|
35
|
+
the strategy metadata and package resource.
|
|
36
|
+
|
|
37
|
+
## Imported Packages
|
|
38
|
+
|
|
39
|
+
`Strategy.use_package(path)` mounts one package into an existing shell:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from aaax import Strategy
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
shell = Strategy("analysis-shell")
|
|
46
|
+
shell.use_package("packages/sources", prefix="sources")
|
|
47
|
+
shell.use_package("packages/analysts", prefix="analysts")
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Prefixes only affect local shell names. The original `psi://` refs stay in
|
|
51
|
+
the resource records.
|
|
52
|
+
|
|
53
|
+
## Binding
|
|
54
|
+
|
|
55
|
+
When `bind=True`, AAAX tries to bind:
|
|
56
|
+
|
|
57
|
+
- Python tactic entrypoints through LLLM's `Tactic` or `as_tactic` boundary.
|
|
58
|
+
- Package channels to a local SSSN `LocalStore`.
|
|
59
|
+
- Services that declare one `tactic` to the same tactic handler.
|
|
60
|
+
|
|
61
|
+
Use `bind=False` when you only want the mount table and metadata:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
shell.use_package("packages/remote-only", bind=False)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
That is useful for remote packages, planning tools, and agent handoff contexts
|
|
68
|
+
where another process will resolve the actual service URLs.
|