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.
Files changed (60) hide show
  1. aaax-0.2.2/MANIFEST.in +11 -0
  2. {aaax-0.2.0 → aaax-0.2.2}/PKG-INFO +20 -5
  3. {aaax-0.2.0 → aaax-0.2.2}/README.md +19 -4
  4. {aaax-0.2.0 → aaax-0.2.2}/aaax/__init__.py +1 -1
  5. {aaax-0.2.0 → aaax-0.2.2}/aaax/server.py +1 -1
  6. {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/PKG-INFO +20 -5
  7. aaax-0.2.2/aaax.egg-info/SOURCES.txt +57 -0
  8. aaax-0.2.2/assets/aaax-logo-text-black.png +0 -0
  9. aaax-0.2.2/assets/aaax-logo-text-white.png +0 -0
  10. aaax-0.2.2/docs/CNAME +1 -0
  11. aaax-0.2.2/docs/assets/aaax-logo-black.png +0 -0
  12. aaax-0.2.2/docs/assets/aaax-logo-text-black.png +0 -0
  13. aaax-0.2.2/docs/assets/aaax-logo-text-white.png +0 -0
  14. aaax-0.2.2/docs/assets/aaax-logo-white.png +0 -0
  15. aaax-0.2.2/docs/composition/channels-services.md +78 -0
  16. aaax-0.2.2/docs/composition/index.md +48 -0
  17. aaax-0.2.2/docs/composition/psihub-packages.md +68 -0
  18. aaax-0.2.2/docs/composition/strategy-resources.md +74 -0
  19. aaax-0.2.2/docs/concepts/launch-boundary.md +50 -0
  20. aaax-0.2.2/docs/concepts/package-composition.md +68 -0
  21. aaax-0.2.2/docs/concepts/strategies.md +73 -0
  22. aaax-0.2.2/docs/getting-started.md +126 -0
  23. aaax-0.2.2/docs/index.md +121 -0
  24. aaax-0.2.2/docs/javascripts/mermaid-init.20260629.js +286 -0
  25. aaax-0.2.2/docs/javascripts/vendor/mermaid-LICENSE.txt +21 -0
  26. aaax-0.2.2/docs/javascripts/vendor/mermaid.min.js +2029 -0
  27. aaax-0.2.2/docs/launch/agent-handoff.md +51 -0
  28. aaax-0.2.2/docs/launch/cli-shell.md +47 -0
  29. aaax-0.2.2/docs/launch/fastapi-surface.md +93 -0
  30. aaax-0.2.2/docs/launch/index.md +32 -0
  31. aaax-0.2.2/docs/overrides/partials/header.html +96 -0
  32. aaax-0.2.2/docs/overrides/partials/nav.html +64 -0
  33. aaax-0.2.2/docs/overrides/partials/source.html +10 -0
  34. aaax-0.2.2/docs/reference/cli.md +45 -0
  35. aaax-0.2.2/docs/reference/http-api.md +69 -0
  36. aaax-0.2.2/docs/reference/python-api.md +87 -0
  37. aaax-0.2.2/docs/stylesheets/custom.20260702.css +732 -0
  38. aaax-0.2.2/docs/tutorials/channel-events.md +58 -0
  39. aaax-0.2.2/docs/tutorials/compose-packages.md +67 -0
  40. aaax-0.2.2/docs/tutorials/serve-package.md +76 -0
  41. aaax-0.2.2/docs/tutorials/tactic-endpoint.md +49 -0
  42. aaax-0.2.2/mkdocs.yml +101 -0
  43. {aaax-0.2.0 → aaax-0.2.2}/pyproject.toml +1 -1
  44. {aaax-0.2.0 → aaax-0.2.2}/tests/test_docs_rendering.py +3 -3
  45. aaax-0.2.2/tests/test_sdist_contents.py +59 -0
  46. aaax-0.2.0/aaax.egg-info/SOURCES.txt +0 -20
  47. {aaax-0.2.0 → aaax-0.2.2}/LICENSE +0 -0
  48. {aaax-0.2.0 → aaax-0.2.2}/aaax/__main__.py +0 -0
  49. {aaax-0.2.0 → aaax-0.2.2}/aaax/cli.py +0 -0
  50. {aaax-0.2.0 → aaax-0.2.2}/aaax/loader.py +0 -0
  51. {aaax-0.2.0 → aaax-0.2.2}/aaax/models.py +0 -0
  52. {aaax-0.2.0 → aaax-0.2.2}/aaax/packages.py +0 -0
  53. {aaax-0.2.0 → aaax-0.2.2}/aaax/py.typed +0 -0
  54. {aaax-0.2.0 → aaax-0.2.2}/aaax/strategy.py +0 -0
  55. {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/dependency_links.txt +0 -0
  56. {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/entry_points.txt +0 -0
  57. {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/requires.txt +0 -0
  58. {aaax-0.2.0 → aaax-0.2.2}/aaax.egg-info/top_level.txt +0 -0
  59. {aaax-0.2.0 → aaax-0.2.2}/setup.cfg +0 -0
  60. {aaax-0.2.0 → aaax-0.2.2}/tests/test_strategy.py +0 -0
aaax-0.2.2/MANIFEST.in ADDED
@@ -0,0 +1,11 @@
1
+ include LICENSE
2
+ include README.md
3
+ include mkdocs.yml
4
+ recursive-include assets *
5
+ recursive-include docs *
6
+ prune build
7
+ prune dist
8
+ prune site
9
+ global-exclude __pycache__
10
+ global-exclude *.py[cod]
11
+ global-exclude .DS_Store
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: aaax
3
- Version: 0.2.0
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
- AAAX is the PSI shell for package-shaped agent systems.
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 coding agent. The feel is intentionally shell-like: name the package,
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
- AAAX is the PSI shell for package-shaped agent systems.
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 coding agent. The feel is intentionally shell-like: name the package,
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
@@ -11,7 +11,7 @@ from .server import create_strategy_app
11
11
  from .strategy import Strategy
12
12
  from .packages import add_package, strategy_from_package
13
13
 
14
- __version__ = "0.2.0"
14
+ __version__ = "0.2.2"
15
15
 
16
16
  __all__ = [
17
17
  "Strategy",
@@ -17,7 +17,7 @@ def create_strategy_app(strategy: Strategy) -> FastAPI:
17
17
  app = FastAPI(
18
18
  title=strategy.name,
19
19
  description=strategy.description,
20
- version="0.2.0",
20
+ version="0.2.2",
21
21
  )
22
22
  app.state.aaax_strategy = strategy
23
23
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: aaax
3
- Version: 0.2.0
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
- AAAX is the PSI shell for package-shaped agent systems.
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 coding agent. The feel is intentionally shell-like: name the package,
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
aaax-0.2.2/docs/CNAME ADDED
@@ -0,0 +1 @@
1
+ aaax.one
@@ -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.