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.
- naas_abi_sdk-0.1.0/.gitignore +161 -0
- naas_abi_sdk-0.1.0/=0.9.13 +1 -0
- naas_abi_sdk-0.1.0/AGENTS.md +181 -0
- naas_abi_sdk-0.1.0/CHANGELOG.md +7 -0
- naas_abi_sdk-0.1.0/Makefile +14 -0
- naas_abi_sdk-0.1.0/PKG-INFO +760 -0
- naas_abi_sdk-0.1.0/README.md +735 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/__init__.py +82 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/activity_log.py +29 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agent.py +413 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agent_host.py +826 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agent_tools.py +50 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/__init__.py +26 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/_messages.py +713 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/agent.py +945 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/hosting.py +58 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/intent_agent.py +470 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/intent_mapper.py +76 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/agents/intents.py +202 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/app_host.py +902 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/app_streams.py +337 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/apps.py +135 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/broker_flush.py +37 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/bus.py +162 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/cache.py +57 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/catalog.py +148 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/claim_check.py +120 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/client.py +70 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/coding_environment.py +76 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/concurrency.py +86 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/dataset.py +70 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/discovery.py +499 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/document.py +104 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/email.py +29 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/event.py +48 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/event_filter.py +87 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/health.py +100 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/job_host.py +996 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/jobs.py +665 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/keyvalue.py +55 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/langgraph.py +420 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/langgraph_documents.py +796 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/lifeline.py +114 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/messages.py +36 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/model_codec.py +61 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/model_host.py +168 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/model_registry.py +55 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/models.py +268 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/module.py +641 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/module_runner.py +55 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/no_responders.py +68 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/object_storage.py +51 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/overflow.py +116 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/py.typed +0 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/redaction.py +72 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/secret.py +29 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/service_token.py +147 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/AGENTS.md +19 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/__init__.py +40 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_activity_log.py +27 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_codec.py +168 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_coding_environment.py +71 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_dataset.py +70 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_email.py +48 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_source_control.py +227 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/_streams.py +81 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/activity_log.py +58 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/cache.py +134 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/dataset.py +104 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/document.py +203 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/errors.py +67 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/event.py +193 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/keyvalue.py +39 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/model_registry.py +59 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/models.py +377 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/object_storage.py +155 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/secret.py +23 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/triple_store.py +208 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/services/vector_store.py +200 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/source_control.py +199 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/streams.py +32 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/telemetry.py +430 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/transfer.py +179 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/transport.py +304 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/triple_store.py +74 -0
- naas_abi_sdk-0.1.0/naas_abi_sdk/vector_store.py +100 -0
- naas_abi_sdk-0.1.0/pyproject.toml +74 -0
- naas_abi_sdk-0.1.0/tests/broker_users.py +70 -0
- naas_abi_sdk-0.1.0/tests/conftest.py +39 -0
- naas_abi_sdk-0.1.0/tests/overflow_fakes.py +45 -0
- naas_abi_sdk-0.1.0/tests/test_agent.py +295 -0
- naas_abi_sdk-0.1.0/tests/test_agent_host.py +854 -0
- naas_abi_sdk-0.1.0/tests/test_agents_hosting.py +123 -0
- naas_abi_sdk-0.1.0/tests/test_app_host.py +795 -0
- naas_abi_sdk-0.1.0/tests/test_app_streams.py +831 -0
- naas_abi_sdk-0.1.0/tests/test_broker_flush.py +70 -0
- naas_abi_sdk-0.1.0/tests/test_claim_check.py +169 -0
- naas_abi_sdk-0.1.0/tests/test_concurrency.py +134 -0
- naas_abi_sdk-0.1.0/tests/test_discovery.py +292 -0
- naas_abi_sdk-0.1.0/tests/test_document.py +51 -0
- naas_abi_sdk-0.1.0/tests/test_document_pages.py +57 -0
- naas_abi_sdk-0.1.0/tests/test_event_activity_streams.py +168 -0
- naas_abi_sdk-0.1.0/tests/test_health.py +105 -0
- naas_abi_sdk-0.1.0/tests/test_job_host.py +1663 -0
- naas_abi_sdk-0.1.0/tests/test_jobs.py +534 -0
- naas_abi_sdk-0.1.0/tests/test_jobs_integration.py +983 -0
- naas_abi_sdk-0.1.0/tests/test_langgraph.py +49 -0
- naas_abi_sdk-0.1.0/tests/test_langgraph_documents.py +435 -0
- naas_abi_sdk-0.1.0/tests/test_lifeline.py +256 -0
- naas_abi_sdk-0.1.0/tests/test_messages.py +55 -0
- naas_abi_sdk-0.1.0/tests/test_model_host.py +222 -0
- naas_abi_sdk-0.1.0/tests/test_models.py +186 -0
- naas_abi_sdk-0.1.0/tests/test_module.py +213 -0
- naas_abi_sdk-0.1.0/tests/test_no_responders.py +218 -0
- naas_abi_sdk-0.1.0/tests/test_overflow.py +73 -0
- naas_abi_sdk-0.1.0/tests/test_redaction.py +86 -0
- naas_abi_sdk-0.1.0/tests/test_require_nats_server.py +68 -0
- naas_abi_sdk-0.1.0/tests/test_service_token.py +125 -0
- naas_abi_sdk-0.1.0/tests/test_services.py +459 -0
- naas_abi_sdk-0.1.0/tests/test_telemetry.py +321 -0
- naas_abi_sdk-0.1.0/tests/test_transfer.py +65 -0
- naas_abi_sdk-0.1.0/tests/test_transport.py +245 -0
- naas_abi_sdk-0.1.0/tests/test_vector_and_generated_services.py +147 -0
- naas_abi_sdk-0.1.0/tests/test_vector_store_stream.py +114 -0
- naas_abi_sdk-0.1.0/tools/generate_services.py +241 -0
- 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,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
|