naas-abi-sdk 0.1.0__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 (126) hide show
  1. naas_abi_sdk-0.1.0/.gitignore +161 -0
  2. naas_abi_sdk-0.1.0/=0.9.13 +1 -0
  3. naas_abi_sdk-0.1.0/AGENTS.md +181 -0
  4. naas_abi_sdk-0.1.0/CHANGELOG.md +7 -0
  5. naas_abi_sdk-0.1.0/Makefile +14 -0
  6. naas_abi_sdk-0.1.0/PKG-INFO +760 -0
  7. naas_abi_sdk-0.1.0/README.md +735 -0
  8. naas_abi_sdk-0.1.0/naas_abi_sdk/__init__.py +82 -0
  9. naas_abi_sdk-0.1.0/naas_abi_sdk/activity_log.py +29 -0
  10. naas_abi_sdk-0.1.0/naas_abi_sdk/agent.py +413 -0
  11. naas_abi_sdk-0.1.0/naas_abi_sdk/agent_host.py +826 -0
  12. naas_abi_sdk-0.1.0/naas_abi_sdk/agent_tools.py +50 -0
  13. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/__init__.py +26 -0
  14. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/_messages.py +713 -0
  15. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/agent.py +945 -0
  16. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/hosting.py +58 -0
  17. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/intent_agent.py +470 -0
  18. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/intent_mapper.py +76 -0
  19. naas_abi_sdk-0.1.0/naas_abi_sdk/agents/intents.py +202 -0
  20. naas_abi_sdk-0.1.0/naas_abi_sdk/app_host.py +902 -0
  21. naas_abi_sdk-0.1.0/naas_abi_sdk/app_streams.py +337 -0
  22. naas_abi_sdk-0.1.0/naas_abi_sdk/apps.py +135 -0
  23. naas_abi_sdk-0.1.0/naas_abi_sdk/broker_flush.py +37 -0
  24. naas_abi_sdk-0.1.0/naas_abi_sdk/bus.py +162 -0
  25. naas_abi_sdk-0.1.0/naas_abi_sdk/cache.py +57 -0
  26. naas_abi_sdk-0.1.0/naas_abi_sdk/catalog.py +148 -0
  27. naas_abi_sdk-0.1.0/naas_abi_sdk/claim_check.py +120 -0
  28. naas_abi_sdk-0.1.0/naas_abi_sdk/client.py +70 -0
  29. naas_abi_sdk-0.1.0/naas_abi_sdk/coding_environment.py +76 -0
  30. naas_abi_sdk-0.1.0/naas_abi_sdk/concurrency.py +86 -0
  31. naas_abi_sdk-0.1.0/naas_abi_sdk/dataset.py +70 -0
  32. naas_abi_sdk-0.1.0/naas_abi_sdk/discovery.py +499 -0
  33. naas_abi_sdk-0.1.0/naas_abi_sdk/document.py +104 -0
  34. naas_abi_sdk-0.1.0/naas_abi_sdk/email.py +29 -0
  35. naas_abi_sdk-0.1.0/naas_abi_sdk/event.py +48 -0
  36. naas_abi_sdk-0.1.0/naas_abi_sdk/event_filter.py +87 -0
  37. naas_abi_sdk-0.1.0/naas_abi_sdk/health.py +100 -0
  38. naas_abi_sdk-0.1.0/naas_abi_sdk/job_host.py +996 -0
  39. naas_abi_sdk-0.1.0/naas_abi_sdk/jobs.py +665 -0
  40. naas_abi_sdk-0.1.0/naas_abi_sdk/keyvalue.py +55 -0
  41. naas_abi_sdk-0.1.0/naas_abi_sdk/langgraph.py +420 -0
  42. naas_abi_sdk-0.1.0/naas_abi_sdk/langgraph_documents.py +796 -0
  43. naas_abi_sdk-0.1.0/naas_abi_sdk/lifeline.py +114 -0
  44. naas_abi_sdk-0.1.0/naas_abi_sdk/messages.py +36 -0
  45. naas_abi_sdk-0.1.0/naas_abi_sdk/model_codec.py +61 -0
  46. naas_abi_sdk-0.1.0/naas_abi_sdk/model_host.py +168 -0
  47. naas_abi_sdk-0.1.0/naas_abi_sdk/model_registry.py +55 -0
  48. naas_abi_sdk-0.1.0/naas_abi_sdk/models.py +268 -0
  49. naas_abi_sdk-0.1.0/naas_abi_sdk/module.py +641 -0
  50. naas_abi_sdk-0.1.0/naas_abi_sdk/module_runner.py +55 -0
  51. naas_abi_sdk-0.1.0/naas_abi_sdk/no_responders.py +68 -0
  52. naas_abi_sdk-0.1.0/naas_abi_sdk/object_storage.py +51 -0
  53. naas_abi_sdk-0.1.0/naas_abi_sdk/overflow.py +116 -0
  54. naas_abi_sdk-0.1.0/naas_abi_sdk/py.typed +0 -0
  55. naas_abi_sdk-0.1.0/naas_abi_sdk/redaction.py +72 -0
  56. naas_abi_sdk-0.1.0/naas_abi_sdk/secret.py +29 -0
  57. naas_abi_sdk-0.1.0/naas_abi_sdk/service_token.py +147 -0
  58. naas_abi_sdk-0.1.0/naas_abi_sdk/services/AGENTS.md +19 -0
  59. naas_abi_sdk-0.1.0/naas_abi_sdk/services/__init__.py +40 -0
  60. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_activity_log.py +27 -0
  61. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_codec.py +168 -0
  62. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_coding_environment.py +71 -0
  63. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_dataset.py +70 -0
  64. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_email.py +48 -0
  65. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_source_control.py +227 -0
  66. naas_abi_sdk-0.1.0/naas_abi_sdk/services/_streams.py +81 -0
  67. naas_abi_sdk-0.1.0/naas_abi_sdk/services/activity_log.py +58 -0
  68. naas_abi_sdk-0.1.0/naas_abi_sdk/services/cache.py +134 -0
  69. naas_abi_sdk-0.1.0/naas_abi_sdk/services/dataset.py +104 -0
  70. naas_abi_sdk-0.1.0/naas_abi_sdk/services/document.py +203 -0
  71. naas_abi_sdk-0.1.0/naas_abi_sdk/services/errors.py +67 -0
  72. naas_abi_sdk-0.1.0/naas_abi_sdk/services/event.py +193 -0
  73. naas_abi_sdk-0.1.0/naas_abi_sdk/services/keyvalue.py +39 -0
  74. naas_abi_sdk-0.1.0/naas_abi_sdk/services/model_registry.py +59 -0
  75. naas_abi_sdk-0.1.0/naas_abi_sdk/services/models.py +377 -0
  76. naas_abi_sdk-0.1.0/naas_abi_sdk/services/object_storage.py +155 -0
  77. naas_abi_sdk-0.1.0/naas_abi_sdk/services/secret.py +23 -0
  78. naas_abi_sdk-0.1.0/naas_abi_sdk/services/triple_store.py +208 -0
  79. naas_abi_sdk-0.1.0/naas_abi_sdk/services/vector_store.py +200 -0
  80. naas_abi_sdk-0.1.0/naas_abi_sdk/source_control.py +199 -0
  81. naas_abi_sdk-0.1.0/naas_abi_sdk/streams.py +32 -0
  82. naas_abi_sdk-0.1.0/naas_abi_sdk/telemetry.py +430 -0
  83. naas_abi_sdk-0.1.0/naas_abi_sdk/transfer.py +179 -0
  84. naas_abi_sdk-0.1.0/naas_abi_sdk/transport.py +304 -0
  85. naas_abi_sdk-0.1.0/naas_abi_sdk/triple_store.py +74 -0
  86. naas_abi_sdk-0.1.0/naas_abi_sdk/vector_store.py +100 -0
  87. naas_abi_sdk-0.1.0/pyproject.toml +74 -0
  88. naas_abi_sdk-0.1.0/tests/broker_users.py +70 -0
  89. naas_abi_sdk-0.1.0/tests/conftest.py +39 -0
  90. naas_abi_sdk-0.1.0/tests/overflow_fakes.py +45 -0
  91. naas_abi_sdk-0.1.0/tests/test_agent.py +295 -0
  92. naas_abi_sdk-0.1.0/tests/test_agent_host.py +854 -0
  93. naas_abi_sdk-0.1.0/tests/test_agents_hosting.py +123 -0
  94. naas_abi_sdk-0.1.0/tests/test_app_host.py +795 -0
  95. naas_abi_sdk-0.1.0/tests/test_app_streams.py +831 -0
  96. naas_abi_sdk-0.1.0/tests/test_broker_flush.py +70 -0
  97. naas_abi_sdk-0.1.0/tests/test_claim_check.py +169 -0
  98. naas_abi_sdk-0.1.0/tests/test_concurrency.py +134 -0
  99. naas_abi_sdk-0.1.0/tests/test_discovery.py +292 -0
  100. naas_abi_sdk-0.1.0/tests/test_document.py +51 -0
  101. naas_abi_sdk-0.1.0/tests/test_document_pages.py +57 -0
  102. naas_abi_sdk-0.1.0/tests/test_event_activity_streams.py +168 -0
  103. naas_abi_sdk-0.1.0/tests/test_health.py +105 -0
  104. naas_abi_sdk-0.1.0/tests/test_job_host.py +1663 -0
  105. naas_abi_sdk-0.1.0/tests/test_jobs.py +534 -0
  106. naas_abi_sdk-0.1.0/tests/test_jobs_integration.py +983 -0
  107. naas_abi_sdk-0.1.0/tests/test_langgraph.py +49 -0
  108. naas_abi_sdk-0.1.0/tests/test_langgraph_documents.py +435 -0
  109. naas_abi_sdk-0.1.0/tests/test_lifeline.py +256 -0
  110. naas_abi_sdk-0.1.0/tests/test_messages.py +55 -0
  111. naas_abi_sdk-0.1.0/tests/test_model_host.py +222 -0
  112. naas_abi_sdk-0.1.0/tests/test_models.py +186 -0
  113. naas_abi_sdk-0.1.0/tests/test_module.py +213 -0
  114. naas_abi_sdk-0.1.0/tests/test_no_responders.py +218 -0
  115. naas_abi_sdk-0.1.0/tests/test_overflow.py +73 -0
  116. naas_abi_sdk-0.1.0/tests/test_redaction.py +86 -0
  117. naas_abi_sdk-0.1.0/tests/test_require_nats_server.py +68 -0
  118. naas_abi_sdk-0.1.0/tests/test_service_token.py +125 -0
  119. naas_abi_sdk-0.1.0/tests/test_services.py +459 -0
  120. naas_abi_sdk-0.1.0/tests/test_telemetry.py +321 -0
  121. naas_abi_sdk-0.1.0/tests/test_transfer.py +65 -0
  122. naas_abi_sdk-0.1.0/tests/test_transport.py +245 -0
  123. naas_abi_sdk-0.1.0/tests/test_vector_and_generated_services.py +147 -0
  124. naas_abi_sdk-0.1.0/tests/test_vector_store_stream.py +114 -0
  125. naas_abi_sdk-0.1.0/tools/generate_services.py +241 -0
  126. naas_abi_sdk-0.1.0/uv.lock +1916 -0
@@ -0,0 +1,161 @@
1
+ # Environment files
2
+ .env
3
+ .env.*
4
+ !.env.example
5
+ libs/naas-abi/naas_abi/apps/nexus/.env
6
+ libs/naas-abi/naas_abi/apps/nexus/apps/api/.env
7
+
8
+ # Virtual Environment
9
+ .venv/
10
+ venv/
11
+ ENV/
12
+ env/
13
+
14
+ # Config
15
+ config.yaml
16
+ config.*.yaml
17
+ !config.local.yaml
18
+ !config.dev.yaml
19
+ !config.remote.yaml
20
+ # App-level configs are source, not environment: the rules above exist for the
21
+ # engine's own config at the repo root, and would otherwise swallow these.
22
+ !libs/naas-abi-marketplace/naas_abi_marketplace/applications/x/apps/*/config.yaml
23
+ !libs/naas-abi-marketplace/naas_abi_marketplace/domains/personnel/apps/cockpit/config.yaml
24
+
25
+ # Python
26
+ __pycache__/
27
+ *.py[cod]
28
+ *$py.class
29
+ *.so
30
+ .Python
31
+ build/
32
+ # The docs section on building (docs/site/docs/user-guide/build/) is not a build output.
33
+ !/docs/site/docs/user-guide/build/
34
+ develop-eggs/
35
+ dist/
36
+ downloads/
37
+ eggs/
38
+ .eggs/
39
+ #lib/
40
+ lib64/
41
+ parts/
42
+ sdist/
43
+ var/
44
+ wheels/
45
+ *.egg-info/
46
+ .installed.cfg
47
+ *.egg
48
+ .mypy_cache/
49
+ .pytest_cache/
50
+ .ruff_cache/
51
+ .pytype
52
+
53
+ # IDEs and editors
54
+ .idea/
55
+ .vscode/
56
+ *.swp
57
+ *.swo
58
+ .DS_Store
59
+
60
+ # Terminal recordings
61
+ *.cast
62
+ *.rec
63
+ *.asciinema
64
+ *.terminal
65
+
66
+ # Docker
67
+ .docker/
68
+
69
+ # Logs
70
+ *.log
71
+
72
+ # Project specific
73
+ thread_id.txt
74
+ agentic-director/
75
+
76
+ # Storage - ignore everything in storage except README files
77
+ storage/*
78
+ !storage/README.md
79
+ !storage/*/README.md
80
+ !storage/datastore/
81
+ !storage/triplestore/
82
+ # Caches written when tests or the CLI run inside a package folder
83
+ libs/*/storage/
84
+ !storage/vectorstore/
85
+ storage/datastore/*
86
+ storage/triplestore/*
87
+ storage/vectorstore/*
88
+
89
+ # Ignore data files globally
90
+ *.csv
91
+ *.parquet
92
+ *.pdf
93
+ *.doc
94
+ *.docx
95
+ *.ppt
96
+ *.pptx
97
+ *.xls
98
+ *.xlsx
99
+ *.jpg
100
+ *.png
101
+ *.gif
102
+ *.jpeg
103
+ *.webp
104
+ *.heic
105
+
106
+ # Allow docs static assets
107
+ !docs/site/static/**/*.png
108
+ !docs/site/static/**/*.jpg
109
+ !docs/site/static/**/*.gif
110
+ !docs/site/static/**/*.jpeg
111
+ !docs/site/static/**/*.webp
112
+ !docs/site/static/**/*.svg
113
+
114
+ # Keep demo data and assets in nexus
115
+ !libs/naas-abi/naas_abi/apps/nexus/demo/**
116
+ !libs/naas-abi/naas_abi/apps/nexus/apps/*/public/**
117
+
118
+ # Financial cockpit brand source files (`npm run sync:brand`)
119
+ !libs/naas-abi-marketplace/naas_abi_marketplace/domains/finance/apps/financial_cockpit/web/assets/**
120
+
121
+
122
+ # `abi dev` runtime artefacts (per-worktree instance/pid/log files)
123
+ .abi/
124
+ # Same artefacts when this repo is the consumer's `.abi` checkout.
125
+ # `{consumer}/.abi/dev` is `{this-repo}/dev`.
126
+ /dev/
127
+ # Dagster local home dir created by `abi dev up`
128
+ .dagster/
129
+ # Local Docker stack snapshots (abi stack snapshot create)
130
+ .snapshots/
131
+
132
+
133
+ *.pid
134
+ sandbox/
135
+
136
+ # Coverage reports
137
+ .coverage
138
+ coverage.xml
139
+ htmlcov/
140
+ secrets.yaml
141
+
142
+ # Docusaurus build output
143
+ docs/site/build/
144
+ docs/site/.docusaurus/
145
+ docs/site/node_modules/
146
+
147
+ # Legacy / deprecated doc systems (Quartz, Next.js legacy site)
148
+ docs/.quartz_conf/
149
+ docs/legacy/
150
+ docs/next/
151
+
152
+ # Docusaurus
153
+ website/node_modules
154
+ website/.docusaurus
155
+ website/build
156
+ .claude/
157
+
158
+ .pnpm-store/
159
+ node_modules/
160
+
161
+ CLAUDE.md
@@ -0,0 +1 @@
1
+ Requirement already satisfied: uv in /opt/hostedtoolcache/Python/3.12.15/x64/lib/python3.12/site-packages (0.13.3)
@@ -0,0 +1,181 @@
1
+ # Standalone package
2
+
3
+ Keep this package independent of naas-abi-core, naas-abi, and marketplace.
4
+ Transport DTOs are protobuf messages. Public service facades expose Python values
5
+ and generated SDK dataclasses, never engine domain objects. See services/AGENTS.md.
6
+ Generated artifacts are checked in; regenerate with `make generate` in the proto package.
7
+ Use UV. `make deps`, `make test`, `make lint`, and `make build` are the local gates.
8
+ Tests live under tests/. Update the standalone module demonstration when adding endpoints.
9
+ After subscribing (or publishing) and before saying so, `await flush_to_broker(nc)` (`broker_flush.py`), never `nc.flush()`:
10
+ nats-py's PING overtakes the buffered SUBs, so a request right after could find no responder. Core re-uses it.
11
+
12
+ LangGraph support lives in langgraph.py and is opt-in via [langgraph]; never import
13
+ it from package __init__ or make it a base dependency. Only async graph execution
14
+ is supported. Keep checkpoint schema versions and pending-write semantics explicit.
15
+ Document module namespaces are a programming boundary, not authorization.
16
+ The document schema is in langgraph_documents.py, shared with core's synchronous
17
+ engine saver and the Nexus viewer: collections, ids, write plans (schema 2 stores
18
+ increments: content-addressed blobs, list elements and chunks, parts above
19
+ 256 KiB), byte-bounded read batches, decoding, and schema 1 reads. Savers only do
20
+ I/O. Stored documents depend on it, so change it only with a schema version.
21
+ Keep it core-free and importable on Python 3.10; tests/test_langgraph_documents.py
22
+ pins the ids. Never deserialize in the pure read helpers (the viewer relies on it).
23
+ It also holds retention (`kept_checkpoints`, `RetentionReport`; the savers'
24
+ `prune`/`aprune` do the I/O) and secret redaction (`RedactingSerializer`: a
25
+ `SecretStr`/`SecretBytes` is stored as one holding `REDACTED_SECRET`, never in
26
+ clear). Redaction does not change the document layout.
27
+
28
+
29
+ AgentProxy and AgentHost use document CAS for durable invocations. A conversation
30
+ claim is released when its owner instance is absent from a successful discovery
31
+ lookup, so that thread can accept a new run. The orphaned invocation is marked
32
+ failed and is not replayed. A failed lookup keeps the claim. This process never
33
+ treats its own instance as absent. A lost lease (expiry or eviction) registers
34
+ the same instance id again with a fresh lease token, so run owners, claims and
35
+ agent and model subjects stay valid; `AgentHost._bind` keeps its subscriptions
36
+ when the id did not change. A provider process accepts at most 200 live
37
+ runs, shared by every agent it hosts. `AgentHost` and `ModelHost` answer their
38
+ calls side by side, up to `max_concurrency` (64) at once (`concurrency.py`,
39
+ `ConcurrentCalls`, shared with core's kernel services and discovery): a
40
+ handler awaited in a subscription callback would answer one call at a time.
41
+ `AgentHost.close()` answers the calls received before it cancels runs;
42
+ `ModelHost.close()` cancels the chats still running. `invoke` and `stream_invoke` send a 300
43
+ second deadline unless the caller passes `timeout`; `deadline_seconds` 0 on
44
+ submit still means no deadline. The 300 second idle watchdog cancels a streamed
45
+ run with no new event, and any run without a deadline. An unstreamed run (invoke
46
+ mode, or a handler without `stream_invoke`) reports nothing until it returns, so
47
+ its deadline alone bounds it. Core Agent/IntentAgent compatibility belongs in core's
48
+ RemoteAgentAdapter; only agent_tools imports optional LangChain dependencies.
49
+ Agent streaming preserves string event/data pairs, a tool response's `chat_source: False`
50
+ opt-out, and sequence-based replay.
51
+
52
+ A rollout id (`DiscoveryConfiguration.rollout_id`, or `ABI_ROLLOUT_ID`) marks
53
+ processes that cut over together. `rollout_modules` (or `ABI_ROLLOUT_MODULES`,
54
+ comma-separated) names every module id that must be initialized first. Empty
55
+ means this module alone. Discovery keeps the previous generation `READY` until
56
+ that set is up, then marks it `DRAINING` and serves the new one. `STAGED` is a
57
+ new generation waiting behind a live one. A rollout may add or change agents,
58
+ jobs and models without a contract bump; replicas of one rollout must match.
59
+ Job schedules and consumers are module-wide, so with a rollout id `run_module`
60
+ starts the job host only once discovery reports the instance `READY` or
61
+ `DEGRADED`, never while `STAGED`. Before it can serve, it creates the missing
62
+ job consumers (`JobHost.prepare`: no fetch, no schedule, no change to an
63
+ existing consumer), so a trigger for a new job sent after the cutover waits
64
+ for the host. `SIGTERM` and `SIGINT` drain the
65
+ process: new agent submits, job fetches, model chats and app requests stop,
66
+ accepted runs, jobs and app requests finish, then the process unregisters. A
67
+ streamed app response may finish too, unless it is server-sent events or idle
68
+ for a second: those end with an error, and their readers reconnect elsewhere. A live run keeps its claim until it
69
+ finishes. See the discovery ADR, section "Rollouts and draining (2026-10-05)".
70
+
71
+ `ABI_HEALTH_PORT` (or `run_module(..., health_port=)`) opens a standard-library
72
+ HTTP probe on `ABI_HEALTH_HOST` (default `0.0.0.0`). Unset means no port.
73
+ `GET /health` is liveness and stays 200 while the process is up, including
74
+ `DRAINING` and `STAGED`. `GET /ready` is 200 for `READY`, and for `DISABLED`
75
+ when discovery is off. Every other status is 503. The server closes when the
76
+ module exits.
77
+
78
+ A module can serve a chat model (`ModelDescriptor`, `expose_model`, `ModelHost`).
79
+ Another module calls `engine.modules[id].get_chat_model(name)`. The call is unary,
80
+ instance-addressed, and authorized with `authorize_model`. The handler returns
81
+ text or an `AIMessage` with tool calls. The caller's agent executes the tools.
82
+ Streaming is refused. Engine model registration stays
83
+ on the model registry.
84
+
85
+ Model proxies/codec import optional LangChain through [models]. Never import them
86
+ from package __init__ or the base service catalog. Registry facades lazy-load
87
+ proxies on model lookup. ModelConnection keeps NATS I/O on the resolving loop;
88
+ sync callers must use another thread. Stream IDs are caller-bound, ephemeral,
89
+ sequence-checked handles; never retry inference or cursor reads automatically.
90
+
91
+ `messages.py` sizes messages as the broker does (body and header block) and
92
+ `reply()` answers without echoing the request's headers; use it instead of
93
+ `Msg.respond`. `claim_check.py` carries published, queued and job-trigger
94
+ messages above the broker limit through a JetStream object store
95
+ (docs/adr/20261003_nats-claim-check.md); `BusClient` subscriptions resolve them
96
+ in place. Every raw NATS send is listed in core's
97
+ `engine/nats_send_sites_test.py`: a new one must go through these helpers.
98
+ `overflow.py` is the client side of RPC overflow (payloads above the broker
99
+ limit as transfer/v1 frames, docs/adr/20261003_nats-rpc-overflow.md), used by
100
+ `Transport` and core's `NatsRPCClient`. A call says `Abi-Overflow: 1` before an
101
+ engine may park its reply; never drop that header or download without the
102
+ announced size. `transfer.py` owns shared chunk framing and session cleanup. Object facades stream
103
+ bounded reads; model proxies assemble logical protobuf frames. Preserve owner-loop
104
+ execution, sequence checks, caller binding and no automatic replay. Per-exchange
105
+ RPC timeouts must not impose a total model-generation deadline.
106
+
107
+ Agent output format 2 stores immutable document fragments and manifests before
108
+ publishing the run sequence cursor. Never truncate events or retry uncertain
109
+ writes. Preserve caller authorization on fragment reads and output-format
110
+ negotiation. Membership caches are bounded to one second, not a lease interval.
111
+ `AgentHost` reuses discovery's authorization of a (caller token, agent) for
112
+ status, event and cancel for `AUTHORIZATION_SECONDS` (5 s), never past the
113
+ token's `exp`, and never caches a refusal. A submit always asks discovery.
114
+
115
+ `agents/` (extra `[agent]`) is the core Agent/IntentAgent behaviour, async and
116
+ core-free: same graph node names, prompts, callbacks, hooks and stream_invoke
117
+ events. `_messages.py` and `intents.py` are copied from naas_abi_core on purpose;
118
+ change them together. tests/agent_parity at the repository root runs every
119
+ scenario against both runtimes: extend it before changing either agent. Host an
120
+ agent with `expose_agent(name, agent.as_handler())` and checkpoint it with
121
+ `document_memory(engine.services.document, agent_memory_id(module_id, name))`.
122
+ v1 has no local sub-agents; remote agents (AgentProxy) are passed as tools.
123
+
124
+ Jobs (`jobs.py`, `job_host.py`, ADR docs/adr/20261001_nats-jobs.md) replace Dagster
125
+ schedules. Declare `JobDescriptor`s in `jobs` or use `@job` on async methods; bind
126
+ others with `expose_job`. `JobsMixin` is shared with core modules (sync handlers
127
+ allowed there): keep `jobs.py` importable without `nats` (stdlib and proto only),
128
+ and keep the package `__init__` lazy for the same reason. Triggers are JetStream message schedules (`Cron`, `Every`,
129
+ NATS >= 2.14) and core-NATS events (`OnEvent`, at-most-once bridge). Delivery is
130
+ at-least-once: handlers must be idempotent. One durable pull consumer per job;
131
+ `max_concurrency` is `max_ack_pending`, retries are `nak(delay)`. Attempts are
132
+ handler starts counted on the run record (`max_deliver` is unlimited): a delivery
133
+ that can't read or record its run is nak'ed with backoff and uses none. Publish a
134
+ schedule only when missing or changed, with `Nats-Expected-Last-Subject-Sequence`:
135
+ replacing one restarts an `@every` interval. A run ID belongs to a delivery only
136
+ when `fired_at` matches (a recreated stream reuses sequences). A retry its
137
+ trigger's `Nats-TTL` would not outlive fails the run instead.
138
+ Renew acknowledgement independently of log persistence; supervise renewal failure.
139
+ Save completion before ack/term/nak and retire redelivered terminal records without
140
+ executing handlers again. An unsaved completion keeps its delivery and its slot
141
+ until the store recovers (on purpose; logged as an error after 60 s). Event deduplication requires a source Nats-Msg-Id and
142
+ includes the target module/job; manual idempotency keys are target-scoped too.
143
+ Run records live in the provider's document namespace (`job_runs_<hash(project)>`), written with CAS.
144
+ Cancellation is cooperative (`ctx.cancelled`). tests/test_jobs_integration.py needs
145
+ `nats-server` on PATH; run it after touching schedules, consumers or acks.
146
+ A module triggers its own jobs through its bound host (`trigger_job` for sync
147
+ code, `atrigger_job` for async; `JobsNotHosted` outside a running host), with an
148
+ optional `idempotency_key` (`Nats-Msg-Id` dedup). `ctx.skip(reason)` records a
149
+ run as SKIPPED; hosts prune finished runs (`JobRetention`: skipped after 1 h,
150
+ others after 7 days, 1,000 per job) and fail runs lost with a crashed host
151
+ (`reap_lost_runs`: RUNNING on the last attempt, no heartbeat for 5 min; or
152
+ RUNNING/RETRYING with attempts left whose trigger left the stream).
153
+ `OnEvent(filter=...)` drops events before a
154
+ trigger is published; `event_filter.py` mirrors core's `EventFilter.matches`,
155
+ change them together.
156
+
157
+ `lifeline.py` stops a process whose NATS connection closed for good (nats-py
158
+ gave up reconnecting), so its supervisor restarts it (ADR
159
+ docs/adr/20261008_stop-on-nats-loss.md). Every long-lived connection passes a
160
+ `Lifeline`'s `closed` as `closed_cb` and closes on purpose through
161
+ `Lifeline.close(nc)`: `Transport` here, and in core the shared engine
162
+ connection, the lease and the bus. `run_module` opts in for its run
163
+ (`stopping_on_loss`), core's `api()` in NATS mode without reload; otherwise a
164
+ loss is only logged. Stopping is SIGTERM, then `os._exit(1)` after
165
+ `HARD_EXIT_SECONDS` (20). Opting in is process-wide: tests pass their own `stop`.
166
+
167
+ `telemetry.py` is the one OpenTelemetry implementation (core reuses it): W3C trace
168
+ context in NATS headers, CLIENT spans in `Transport.call`, CONSUMER spans for job
169
+ runs, spans for agent submits and runs, `record_error` on error replies, and the
170
+ owner's SERVER span per transfer session (`serve_transfer`: open to close, expiry
171
+ or stop; current only around the handler). Keep it stdlib plus optional
172
+ OpenTelemetry API, and a no-op without a provider. Modules
173
+ export spans when `OTEL_EXPORTER_OTLP_ENDPOINT` is set (`[otel]` extra). See
174
+ docs/adr/20261002_observability.md.
175
+
176
+ Test layout is a deliberate exception to the monorepo rule of a `_test.py` beside
177
+ each file: SDK tests live in `tests/test_<module>.py`, outside the published
178
+ package, and the CI `packages` job runs them alone on Python 3.10 to 3.12. Add a
179
+ module's tests to its `tests/test_<module>.py`. `tests/conftest.py` fails a test
180
+ skipped for want of `nats-server` when `ABI_REQUIRE_NATS_SERVER=1` (set in CI);
181
+ it mirrors core's `engine/nats_test_server.py` hook, so change them together.
@@ -0,0 +1,7 @@
1
+ # CHANGELOG
2
+
3
+ <!-- version list -->
4
+
5
+ ## v0.1.0 (2026-10-20)
6
+
7
+ - Initial Release
@@ -0,0 +1,14 @@
1
+ .PHONY: deps test lint build generate
2
+ deps:
3
+ uv sync --group dev
4
+ test:
5
+ uv run pytest tests -q
6
+ lint:
7
+ uv run ruff check .
8
+ build:
9
+ uv build
10
+
11
+ generate:
12
+ uv run python tools/generate_services.py
13
+ uv run ruff check --fix naas_abi_sdk/services
14
+ uv run ruff format naas_abi_sdk/services