langchain-submilli 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.
- langchain_submilli-0.1.0/.gitignore +17 -0
- langchain_submilli-0.1.0/CHANGELOG.md +25 -0
- langchain_submilli-0.1.0/LICENSE +201 -0
- langchain_submilli-0.1.0/NOTES.md +287 -0
- langchain_submilli-0.1.0/PKG-INFO +361 -0
- langchain_submilli-0.1.0/README.md +329 -0
- langchain_submilli-0.1.0/examples/research/README.md +32 -0
- langchain_submilli-0.1.0/pyproject.toml +84 -0
- langchain_submilli-0.1.0/src/langchain_submilli/__init__.py +21 -0
- langchain_submilli-0.1.0/src/langchain_submilli/_app_tools.py +444 -0
- langchain_submilli-0.1.0/src/langchain_submilli/_middleware.py +538 -0
- langchain_submilli-0.1.0/src/langchain_submilli/_tools.py +248 -0
- langchain_submilli-0.1.0/src/langchain_submilli/py.typed +0 -0
- langchain_submilli-0.1.0/tests/__init__.py +0 -0
- langchain_submilli-0.1.0/tests/integration_tests/__init__.py +0 -0
- langchain_submilli-0.1.0/tests/integration_tests/conftest.py +129 -0
- langchain_submilli-0.1.0/tests/integration_tests/test_app_tools.py +205 -0
- langchain_submilli-0.1.0/tests/integration_tests/test_research.py +281 -0
- langchain_submilli-0.1.0/tests/scripted.py +59 -0
- langchain_submilli-0.1.0/tests/unit_tests/__init__.py +0 -0
- langchain_submilli-0.1.0/tests/unit_tests/fake_server.py +276 -0
- langchain_submilli-0.1.0/tests/unit_tests/test_app_tools.py +413 -0
- langchain_submilli-0.1.0/tests/unit_tests/test_deepagents.py +58 -0
- langchain_submilli-0.1.0/tests/unit_tests/test_middleware.py +321 -0
- langchain_submilli-0.1.0/tests/unit_tests/test_standard.py +60 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.pyc
|
|
4
|
+
.pytest_cache/
|
|
5
|
+
.mypy_cache/
|
|
6
|
+
.ruff_cache/
|
|
7
|
+
dist/
|
|
8
|
+
build/
|
|
9
|
+
*.egg-info/
|
|
10
|
+
.submilli-bin/
|
|
11
|
+
|
|
12
|
+
# Local only: model and service keys, the test server's home and token
|
|
13
|
+
.env
|
|
14
|
+
.submilli-test/
|
|
15
|
+
.submilli-test.log
|
|
16
|
+
.submilli-token
|
|
17
|
+
.benchmarks/
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are recorded here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.0] - 2026-10-15
|
|
10
|
+
|
|
11
|
+
First release, for submilli-server 0.4.1 and the `submilli` SDK 0.1.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- `SubmilliMiddleware` for deepagents and any LangChain v1 agent: the server's
|
|
16
|
+
six tools, with the Blueprint's descriptions, and one session per thread,
|
|
17
|
+
bound to the variables and secrets from the run's context.
|
|
18
|
+
- Retries with an `Idempotency-Key` per tool call. A session that ended is
|
|
19
|
+
replaced, and the model is told. A thread whose variables changed is refused.
|
|
20
|
+
- `aclose_thread` to end a thread's session.
|
|
21
|
+
- `hide_filesystem_tools` to remove deepagents' own file and shell tools.
|
|
22
|
+
- `ptc` (programmatic tool calling): programs call the application's LangChain tools as `@tools`,
|
|
23
|
+
run through a `ToolNode` with the run's state and context.
|
|
24
|
+
- `interrupt_on` for `ptc` tools: a person approves each call, with
|
|
25
|
+
LangChain's human-in-the-loop request and decision shapes.
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
# Notes
|
|
2
|
+
|
|
3
|
+
These are the decisions the brief left open, and what in submilli-runtime got in the way. The
|
|
4
|
+
package was built and tested against submilli-runtime at `60f2a857` (server 0.4.0, built from
|
|
5
|
+
source; the installed 0.3.0 binary was not used). Application tools (`ptc`, first named `expose_tools`) were added
|
|
6
|
+
for, and tested against, the published 0.4.1 release binaries, which also pass the restart and
|
|
7
|
+
expiry tests. The HTTP client now lives in its own package, `submilli`
|
|
8
|
+
(`packages/submilli` in the same workspace), described below. It was also tested against deepagents 0.7.24, langchain 1.4.5, langchain-core
|
|
9
|
+
1.6.10, and langgraph 1.2.15.
|
|
10
|
+
|
|
11
|
+
## Decisions
|
|
12
|
+
|
|
13
|
+
### Tools
|
|
14
|
+
|
|
15
|
+
- **Names.** The tools keep the server's own names (`submilli__typescript__execute` and the
|
|
16
|
+
rest), without a prefix of ours. The server's responses refer to its tools by these names.
|
|
17
|
+
For example, a package search with no hits points to `submilli__typescript__builtins__docs`.
|
|
18
|
+
A renamed tool would contradict the text the model reads. The names also match the MCP
|
|
19
|
+
endpoint and the Vercel example.
|
|
20
|
+
- **Arguments.** `code`, `query` (default `""`), `name`, and `names`, with the field
|
|
21
|
+
descriptions of the server's MCP tools.
|
|
22
|
+
- **Descriptions.** They come from `GET /v1/blueprints/{name}/prompt`, which the middleware
|
|
23
|
+
fetches on the first model call, in `awrap_model_call`, and caches for the instance. It does
|
|
24
|
+
not fetch them in `__init__`, because that would need a blocking request while the agent is
|
|
25
|
+
built. The descriptions are set on the middleware's own tool objects. Until then, each tool
|
|
26
|
+
has a short fallback description, so it can be inspected before any run.
|
|
27
|
+
- **Result shape.** The content is JSON text with `result`, `console`, `error`, and `denied`, as
|
|
28
|
+
in the Vercel example. A denial adds `note`, which tells the model the denial is final. A
|
|
29
|
+
replaced session adds `notice`. `discovery_warnings` is passed through when present.
|
|
30
|
+
`ToolMessage.status` is `"error"` whenever `error` is set.
|
|
31
|
+
- **Artifact.** The artifact holds `{execution_id, session_id}`. An idempotency refusal adds
|
|
32
|
+
`refusal`, and `execution_id` when the server sent one.
|
|
33
|
+
- **Discovery tools never open a session.** `last_run` in a thread with no session answers in
|
|
34
|
+
text and does not open one.
|
|
35
|
+
- **langchain-core quirk.** A `StructuredTool` whose argument schema has no fields gets no
|
|
36
|
+
arguments at all, the injected `ToolRuntime` included. `last_run` and `builtins__list`
|
|
37
|
+
therefore carry a hidden `runtime` field marked `InjectedToolArg`.
|
|
38
|
+
|
|
39
|
+
### Sessions
|
|
40
|
+
|
|
41
|
+
- **Where the session opens.** The session opens in `aafter_model`, when the model's message
|
|
42
|
+
first asks for `submilli__typescript__execute`. It does not open inside the tool. The update
|
|
43
|
+
from the `after_model` node is checkpointed before the tools node runs. A process that
|
|
44
|
+
crashes mid-call and resumes from that checkpoint retries in the same session, and the
|
|
45
|
+
idempotency key replays the run. Had the session opened inside the tool, the resumed call
|
|
46
|
+
would find no session, open a new one, and run the program a second time. If the tool runs
|
|
47
|
+
without the hook, it opens the session itself, with a per-thread lock, and returns it in a
|
|
48
|
+
`Command`.
|
|
49
|
+
- **State.** The state key is `submilli_session`: `{id, server, blueprint, variables}`. It is
|
|
50
|
+
marked `PrivateStateAttr`, so it is left out of the agent's input and output schemas, and
|
|
51
|
+
applications read it with `aget_state`. Its reducer replaces the old value. Parallel tool
|
|
52
|
+
calls that all find the session gone each write the same replacement, and the default
|
|
53
|
+
channel would reject more than one write in a step.
|
|
54
|
+
- **Variables are stored, secrets are not.** The variables are kept as values, so a mismatch
|
|
55
|
+
is an exact comparison. Secrets are recomputed from the context whenever they are needed.
|
|
56
|
+
- **Mismatch.** `abefore_agent` raises `SubmilliSessionMismatchError` before the model is
|
|
57
|
+
called. The message names the variables that differ, not their values. A mismatch is the
|
|
58
|
+
application's error, so it is raised rather than shown to the model. The tool checks again
|
|
59
|
+
before every execute.
|
|
60
|
+
- **Blueprint or server change on a thread.** When the stored session was opened for another
|
|
61
|
+
Blueprint or server, it is ignored and a new session is opened. The old session is left to
|
|
62
|
+
its idle timeout.
|
|
63
|
+
- **Closing.** `await middleware.aclose_thread(agent, config)` deletes the thread's session and
|
|
64
|
+
sets `submilli_session` to `None` with `aupdate_state`. The next execute opens a new session,
|
|
65
|
+
and it may bind another user. `middleware.client.sessions.delete(id)` is the low-level form.
|
|
66
|
+
Nothing closes a session automatically.
|
|
67
|
+
- **Retries.** On `404 unknown session`, the middleware opens a new session once per call, and
|
|
68
|
+
the next call reuses that replacement. On `409 session_requires_secrets`, it rebinds once and
|
|
69
|
+
retries. A second `409` raises `SubmilliError`.
|
|
70
|
+
- **Errors that are the application's raise; errors that are the model's are tool results.**
|
|
71
|
+
These raise: 401, invalid variables or secrets, an unknown Blueprint, and an unreachable
|
|
72
|
+
server. These come back as tool results: program failures, denials, and idempotency
|
|
73
|
+
refusals.
|
|
74
|
+
|
|
75
|
+
### Idempotency
|
|
76
|
+
|
|
77
|
+
- The key is the tool call id when it is printable ASCII of at most 120 bytes. Otherwise it is
|
|
78
|
+
the sha256 hex digest of the id's UTF-8 bytes.
|
|
79
|
+
- This assumes tool call ids are unique within a thread, as Anthropic's and OpenAI's are. A
|
|
80
|
+
model that reuses an id, as the scripted model in `check.py` does (`call-1` for every call),
|
|
81
|
+
would get the recorded result of an earlier call with the same code. The tests use unique
|
|
82
|
+
ids.
|
|
83
|
+
- Across a session replacement nothing is deduplicated, because the ledger belongs to the
|
|
84
|
+
session.
|
|
85
|
+
|
|
86
|
+
### Configuration
|
|
87
|
+
|
|
88
|
+
- `variables` and `secrets` accept a callable over `runtime.context` or a fixed mapping. The
|
|
89
|
+
default reads `user_id` from a dict key or an attribute, so a dict, a dataclass, and a
|
|
90
|
+
Pydantic model all work, and maps it to `userId`. Values must be strings; anything else raises
|
|
91
|
+
`TypeError`.
|
|
92
|
+
- `client=` takes a ready `submilli.AsyncSubmilli`, which can wrap your own `httpx.AsyncClient`.
|
|
93
|
+
The managed client keeps one `httpx.AsyncClient` per event loop, because applications and tests
|
|
94
|
+
often run several loops.
|
|
95
|
+
- The default request timeout is 330 s. The server may wait up to 300 s for a running request
|
|
96
|
+
with the same idempotency key.
|
|
97
|
+
- **Async only.** The tools' sync entry points raise `NotImplementedError` with a pointer to
|
|
98
|
+
`ainvoke`. deepagents does not require a sync API.
|
|
99
|
+
- One `SubmilliMiddleware` per agent: two instances would share the `submilli_session` key.
|
|
100
|
+
|
|
101
|
+
### deepagents' file tools
|
|
102
|
+
|
|
103
|
+
- The middleware can hide them cleanly. `hide_filesystem_tools=True` filters `ls`, `read_file`,
|
|
104
|
+
`write_file`, `edit_file`, `delete`, `glob`, `grep`, and `execute` out of `request.tools` in
|
|
105
|
+
`awrap_model_call`. deepagents' own `_ToolExclusionMiddleware` uses the same mechanism. The
|
|
106
|
+
flag also refuses a call to one of them in `awrap_tool_call`. deepagents 0.7.24's
|
|
107
|
+
`FilesystemMiddleware` adds no system-prompt text of its own, so no prose is left describing
|
|
108
|
+
the hidden tools. The flag is opt-in, and the example uses it.
|
|
109
|
+
- **Limit.** deepagents' built-in `general-purpose` subagent is built with its own middleware
|
|
110
|
+
list, and user middleware does not reach it. It keeps deepagents' file tools and gets no
|
|
111
|
+
Submilli tools. The README says so, and points to `permissions=` for denying the file tools
|
|
112
|
+
there too.
|
|
113
|
+
- The flag also hides any tool of the app's own with one of those names, `execute` included.
|
|
114
|
+
|
|
115
|
+
### Application tools (`ptc`)
|
|
116
|
+
|
|
117
|
+
Server 0.4.1 shipped SUB-1694: a session declares `tools`, programs call them through `@tools`,
|
|
118
|
+
each call suspends the run in memory, and the harness answers with `POST /v1/runs/{id}/resume`.
|
|
119
|
+
|
|
120
|
+
- **The option is `ptc`, not `tools`.** `AgentMiddleware.tools` is already the list of
|
|
121
|
+
tools a middleware gives the model. These tools are not given to the model. It was first
|
|
122
|
+
`expose_tools`; it was renamed before the first release to match `langchain-quickjs`'s
|
|
123
|
+
`CodeInterpreterMiddleware(ptc=...)`. Unlike there, it takes tool objects only, not names:
|
|
124
|
+
the session declares its tools when it opens, from the execute tool, which does not see the
|
|
125
|
+
agent's tool list.
|
|
126
|
+
- **Declaring.** The input schema is `tool.tool_call_schema`, so injected arguments
|
|
127
|
+
(`ToolRuntime`, `InjectedState`, `InjectedStore`) are not part of it. The output schema comes
|
|
128
|
+
from the function's return annotation through a pydantic `TypeAdapter`. It is `string` when
|
|
129
|
+
there is no annotation, when the annotation is a message, a `Command`, `Any`, or `str`, when
|
|
130
|
+
the tool is not `response_format="content"`, or when the annotation has no JSON schema.
|
|
131
|
+
Local `$ref`s are inlined, because the server's mapper does not resolve `$ref` and would type
|
|
132
|
+
the field `unknown`. A recursive reference becomes `{}`.
|
|
133
|
+
- **What the server can't type.** `dict[str, X]` (`additionalProperties`) comes back
|
|
134
|
+
`unknown`, with a warning when the session opens. It is declared anyway, because a program
|
|
135
|
+
can still narrow an `unknown`. The README tells users to return a `TypedDict` or a model.
|
|
136
|
+
- **Running a call.** It goes through a `ToolNode` built over the exposed tools, invoked with a
|
|
137
|
+
`ToolCallWithContext` and the execute tool's own config. That gives the agent's own injection,
|
|
138
|
+
error handling (`handle_tool_errors=True`, so a raising tool becomes a `failed` answer), and
|
|
139
|
+
`Command` validation. The nested call's id is the server's `call_id`. Other middleware's
|
|
140
|
+
`wrap_tool_call` hooks do not run around nested calls.
|
|
141
|
+
- **Values.** A tool declared as text returns the `ToolMessage` text. A structured tool returns
|
|
142
|
+
the parsed JSON of that text. A `ToolNode` writes a value that isn't JSON as its `str()`, so
|
|
143
|
+
structured tools run through a copy whose function returns `to_jsonable_python(...)`. That
|
|
144
|
+
makes a Pydantic model reach the program as an object. The copy keeps the signature
|
|
145
|
+
(`functools.wraps`), so injected arguments are still detected.
|
|
146
|
+
- **State updates.** A nested tool that returns a `Command` has its non-message updates
|
|
147
|
+
applied with the execute result. `ToolNode` only accepts a dict as a Command's update, so
|
|
148
|
+
updates to the same key are combined: dicts are merged (deepagents' `files`), and anything
|
|
149
|
+
else keeps the last value. A nested `Command.goto` is refused.
|
|
150
|
+
- **Approvals use LangGraph `interrupt()` inside the execute tool.** The request and decision
|
|
151
|
+
shapes are `HumanInTheLoopMiddleware`'s, one action per pause, so existing approval UIs work.
|
|
152
|
+
The hard part is that LangGraph gives a re-run task its earlier resume values by position,
|
|
153
|
+
while the server has already moved past the calls those values answered. Re-running the
|
|
154
|
+
tool replays the execute with the same `Idempotency-Key`, which answers the run's current
|
|
155
|
+
state, but the first interrupt of the re-run would get the first stored value. The middleware
|
|
156
|
+
therefore records, for each run, which call each pause was for. On a re-run it skips the
|
|
157
|
+
interrupts that belong to earlier calls (`interrupt(None)` returns a stored value without
|
|
158
|
+
raising) before it asks for the current one. Two approvals in one program are tested against
|
|
159
|
+
the fake and against a real 0.4.1 server.
|
|
160
|
+
- **The limit of that record.** It lives in the middleware's memory. When the thread is resumed
|
|
161
|
+
in another process, for example another worker, and the task already has resume values,
|
|
162
|
+
they can't be matched to calls. Then the call is answered `denied`, saying the approval
|
|
163
|
+
could not be matched; it is never matched by guessing. Whether the task has resume values is
|
|
164
|
+
read from LangGraph's scratchpad (`langgraph._internal._constants.CONFIG_KEY_SCRATCHPAD`),
|
|
165
|
+
which is private. A server-side history of a run's answered calls would make this
|
|
166
|
+
stateless.
|
|
167
|
+
- **The record also carries** the call records and state updates of a run interrupted
|
|
168
|
+
mid-way, so the invocation that finishes it reports every call, not only those after the
|
|
169
|
+
last pause.
|
|
170
|
+
- **Nested interrupts are not supported.** An exposed tool that calls `interrupt()` itself
|
|
171
|
+
would take resume values meant for approvals.
|
|
172
|
+
- **Lost runs.** A suspended run is lost when the server restarts (`404 unknown_run` on
|
|
173
|
+
resume). The model gets a `run_lost` result saying its effects are unknown, as for
|
|
174
|
+
`idempotency_incomplete`. `409 run_not_suspended` (a call timed out) and `400 unknown_call`
|
|
175
|
+
make the middleware read the run with `GET /v1/runs/{id}` and carry on. A `running` state is
|
|
176
|
+
polled with backoff.
|
|
177
|
+
- **Discovery.** With exposed tools, `packages__search` and `packages__docs` use
|
|
178
|
+
`/v1/sessions/{id}/packages/...`, so `@tools` is included, and those calls open the session
|
|
179
|
+
(in `aafter_model` too). Without exposed tools nothing changes.
|
|
180
|
+
- **Sessions keep their catalog.** `submilli_session.tools` holds a sha256 of the declared
|
|
181
|
+
catalog, and a session whose fingerprint differs is not reused. Sessions stored before this
|
|
182
|
+
field have none, which matches a middleware without exposed tools.
|
|
183
|
+
- **Seen on the real server.** `@tools` docs list every declared tool, including those the
|
|
184
|
+
Blueprint's filter refuses. The filter is checked on each call, which then fails with
|
|
185
|
+
`permission_denied`, `source: policy`, and the application never sees it. A tool with no
|
|
186
|
+
arguments is called as `tools.name()`.
|
|
187
|
+
|
|
188
|
+
### Packaging, tests, CI
|
|
189
|
+
|
|
190
|
+
- The license is Apache-2.0, as submilli-runtime's. Python is 3.11 or later. Dependencies have
|
|
191
|
+
lower bounds at the tested versions, under the next major version (deepagents under 0.8),
|
|
192
|
+
and `uv.lock` pins the tested set. deepagents is an optional extra
|
|
193
|
+
(`langchain-submilli[deepagents]`), because the middleware works with any LangChain v1 agent.
|
|
194
|
+
- The package lives in the `github.com/submilli/submilli-python` workspace, next to `submilli`,
|
|
195
|
+
and its URLs point there.
|
|
196
|
+
- **Standard tests.** `ToolsUnitTests` runs for each of the six tools. `ToolsIntegrationTests`
|
|
197
|
+
invokes a tool synchronously and on its own, without an agent runtime, so it cannot apply
|
|
198
|
+
to these async, state-bound tools. It will apply to the future toolkit.
|
|
199
|
+
- **Integration tests.** Most run against an external server with the `research` Blueprint and
|
|
200
|
+
are skipped when none is reachable. The restart and expiry tests start their own server from
|
|
201
|
+
`SUBMILLI_BIN` or `PATH`, with a small Blueprint that needs no Package and declares a harness
|
|
202
|
+
secret. A restart does not force a `409`: see "Harness secrets survive restarts" below, so the
|
|
203
|
+
rebind path is covered by the unit tests only. Expiry uses `idle_timeout: 1s`: the test stops the server
|
|
204
|
+
for 1.5 s, and the server reaps the session when it starts again. The resume test reopens the
|
|
205
|
+
thread with a new middleware and agent over the same checkpointer, from the checkpoint taken
|
|
206
|
+
just before the tools node.
|
|
207
|
+
- **Typing.** The package ships `py.typed`. `mypy --strict` and pyright check the sources,
|
|
208
|
+
the tests, and the example, and `pyright --verifytypes` requires the public API to be fully
|
|
209
|
+
typed and documented (100%). The internal modules are private (`_middleware.py`, `_tools.py`,
|
|
210
|
+
`_app_tools.py`), and the public API is what `langchain_submilli` exports. Typing found two
|
|
211
|
+
things worth changing. `SubmilliMiddleware` was generic over a context type it could never
|
|
212
|
+
bind, so an agent built with `context_schema=` together with it failed type inference; it is
|
|
213
|
+
now `AgentMiddleware[SubmilliState, Any, Any]`. And the example now declares a `Context`
|
|
214
|
+
schema, so its `ainvoke(context=...)` type-checks.
|
|
215
|
+
- **CI** is the workspace's: ruff, mypy, pyright and `--verifytypes`, and the unit tests on
|
|
216
|
+
Python 3.11 to 3.13. Its integration job downloads the released `submilli-server` and runs
|
|
217
|
+
the tests that start their own server; those that need the `research` Blueprint's Packages
|
|
218
|
+
are skipped there. The integration fixture registers Blueprints over the admin API, so the
|
|
219
|
+
`submilli` CLI, which has no Linux release build, is not needed.
|
|
220
|
+
- The example keeps the brief's model id, `anthropic:claude-sonnet-5`. It uses an
|
|
221
|
+
`InMemorySaver` and closes the thread's session when it exits.
|
|
222
|
+
|
|
223
|
+
### The `submilli` SDK
|
|
224
|
+
|
|
225
|
+
The HTTP client moved out of this package into `submilli`, a separate package in the same
|
|
226
|
+
workspace (`packages/submilli`). It knows the HTTP API and nothing about LangChain, so other
|
|
227
|
+
harnesses can use it. Both are published to PyPI on their own, from one repository, so a
|
|
228
|
+
change that spans both, such as application tools, is one pull request.
|
|
229
|
+
|
|
230
|
+
- **What moved.** The requests, the typed results and errors, `idempotency_key`, `$ref`
|
|
231
|
+
inlining, and the suspend and resume loop (`runs.complete`). The loop takes an
|
|
232
|
+
`on_tool_call` callback and lets an exception from it propagate, which leaves the run
|
|
233
|
+
waiting on the server. That is what a LangGraph interrupt needs.
|
|
234
|
+
- **What stayed.** The middleware, the six tools, the state schema, turning LangChain tools
|
|
235
|
+
into declarations, running nested calls through a `ToolNode`, approvals, and merging state
|
|
236
|
+
updates.
|
|
237
|
+
- **Names.** Some names changed: `IdempotencyRefusedError` is `submilli.IdempotencyError`, and
|
|
238
|
+
`SubmilliHTTPError` is `submilli.APIStatusError` with a subclass for each status. The
|
|
239
|
+
middleware no longer re-exports client types.
|
|
240
|
+
- **The dependency.** `submilli>=0.1.0,<0.2` on PyPI. In the workspace,
|
|
241
|
+
`[tool.uv.sources]` resolves it to `packages/submilli`. The published wheel names the PyPI
|
|
242
|
+
requirement, which CI checks.
|
|
243
|
+
|
|
244
|
+
### Harness secrets survive restarts
|
|
245
|
+
|
|
246
|
+
The HTTP API reference says harness secrets are kept in memory only and do not survive a
|
|
247
|
+
restart. On 0.4.0 and 0.4.1 that is not what happens. The server stores them encrypted with
|
|
248
|
+
its secret-store key, in SQLite (`encrypted_harness_bindings`). It refuses session secrets
|
|
249
|
+
when no key is configured (`409`, "configure the secret-store encryption key before supplying
|
|
250
|
+
session secrets"). After a restart with a different key, it answers `409` "cannot decrypt
|
|
251
|
+
session secrets", not `session_requires_secrets`. The earlier restart test passed without ever
|
|
252
|
+
rebinding; it now says what it checks. The middleware's rebind on `session_requires_secrets`
|
|
253
|
+
stays, because the API still documents that answer.
|
|
254
|
+
|
|
255
|
+
## What in submilli-runtime got in the way
|
|
256
|
+
|
|
257
|
+
Each item below is filed in Linear, in the Submilli team's `server` project.
|
|
258
|
+
|
|
259
|
+
1. **MCP execute ignores idempotency.** (SUB-1685) `mcp/server.rs` passes `idempotency_key: None`. It
|
|
260
|
+
already reads Claude Code's `_meta["claudecode/toolUseId"]`, but only for the run record. If
|
|
261
|
+
the server took a key from MCP `_meta`, as a generic `submilli/idempotencyKey` or by reusing
|
|
262
|
+
the tool call id, MCP harnesses would get the same retry safety as this package.
|
|
263
|
+
2. **HTTP execute cannot carry the tool call id.** (SUB-1686) `handlers/sessions.rs` records
|
|
264
|
+
`tool_call_id: None`. An HTTP harness has no way to put its tool call id in the run's record
|
|
265
|
+
and audit trail, except as the `Idempotency-Key`, which this package hashes when the id is
|
|
266
|
+
long. A `Submilli-Tool-Call-Id` header would close the gap.
|
|
267
|
+
3. **A replay is not marked.** (SUB-1687) A replayed response is byte-identical to the original. A
|
|
268
|
+
`replayed: true` field, or a response header, would let the harness tell the model or the
|
|
269
|
+
application that nothing ran this time.
|
|
270
|
+
4. **Error codes are sometimes prose.** (SUB-1688) `404 {"error":"unknown session"}`,
|
|
271
|
+
`"blueprint no longer exists"`, `"unknown blueprint"`, and the `400` bodies of
|
|
272
|
+
`POST /v1/sessions` (`"invalid variables: ..."`) put a sentence where other endpoints put a
|
|
273
|
+
stable snake_case code. The client has to match those strings.
|
|
274
|
+
5. **`execution_id` on refusals is undocumented.** (SUB-1689) Refusals carry an `execution_id`:
|
|
275
|
+
`404 unknown session`, `409 session_requires_secrets`, and the idempotency refusals. The
|
|
276
|
+
HTTP API reference shows bodies without it.
|
|
277
|
+
6. **`GET last-run` is ambiguous.** (SUB-1690) It answers `404` with an empty body both for an unknown
|
|
278
|
+
session and for a session with no recorded run.
|
|
279
|
+
7. **`idle_timeout` is approximate.** (SUB-1691) A session idle past its timeout keeps answering until the
|
|
280
|
+
next reaper sweep, every 30 s (`REAP_INTERVAL` in `app.rs`), or a restart. That is harmless
|
|
281
|
+
for users, but a test cannot observe real expiry without restarting the server.
|
|
282
|
+
8. **Two names for the server URL.** (SUB-1692) The `submilli server ...` commands read
|
|
283
|
+
`SUBMILLI_SERVER_URL`, while the harness examples, and so this package, use
|
|
284
|
+
`SUBMILLI_SERVER`.
|
|
285
|
+
9. **The HTTP API has no file endpoints.** (SUB-1693) The MCP endpoint has `submilli__files__*`; the HTTP
|
|
286
|
+
API does not. This package therefore has no file tools, and the model reads files with
|
|
287
|
+
programs.
|