aclientp 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 (112) hide show
  1. aclientp-0.1.0/LICENSE +22 -0
  2. aclientp-0.1.0/PKG-INFO +178 -0
  3. aclientp-0.1.0/README.md +132 -0
  4. aclientp-0.1.0/pyproject.toml +345 -0
  5. aclientp-0.1.0/pyproject.toml.orig +338 -0
  6. aclientp-0.1.0/src/aclientp/__init__.py +293 -0
  7. aclientp-0.1.0/src/aclientp/__main__.py +10 -0
  8. aclientp-0.1.0/src/aclientp/_mime.py +51 -0
  9. aclientp-0.1.0/src/aclientp/_tracing.py +26 -0
  10. aclientp-0.1.0/src/aclientp/agent/__init__.py +7 -0
  11. aclientp-0.1.0/src/aclientp/agent/acp_agent_api.py +225 -0
  12. aclientp-0.1.0/src/aclientp/agent/acp_requests.py +279 -0
  13. aclientp-0.1.0/src/aclientp/agent/connection.py +350 -0
  14. aclientp-0.1.0/src/aclientp/agent/implementations/__init__.py +6 -0
  15. aclientp-0.1.0/src/aclientp/agent/implementations/debug_server/__init__.py +1 -0
  16. aclientp-0.1.0/src/aclientp/agent/implementations/debug_server/cli.py +79 -0
  17. aclientp-0.1.0/src/aclientp/agent/implementations/debug_server/debug.html +229 -0
  18. aclientp-0.1.0/src/aclientp/agent/implementations/debug_server/debug_server.py +312 -0
  19. aclientp-0.1.0/src/aclientp/agent/implementations/debug_server/mock_agent.py +177 -0
  20. aclientp-0.1.0/src/aclientp/agent/implementations/debug_server/models.py +54 -0
  21. aclientp-0.1.0/src/aclientp/agent/implementations/testing.py +104 -0
  22. aclientp-0.1.0/src/aclientp/agent/notifications.py +512 -0
  23. aclientp-0.1.0/src/aclientp/agent/protocol.py +150 -0
  24. aclientp-0.1.0/src/aclientp/bridge/README.md +175 -0
  25. aclientp-0.1.0/src/aclientp/bridge/__init__.py +7 -0
  26. aclientp-0.1.0/src/aclientp/bridge/__main__.py +132 -0
  27. aclientp-0.1.0/src/aclientp/bridge/bridge.py +162 -0
  28. aclientp-0.1.0/src/aclientp/bridge/py.typed +0 -0
  29. aclientp-0.1.0/src/aclientp/bridge/settings.py +15 -0
  30. aclientp-0.1.0/src/aclientp/bridge/ws_server.py +157 -0
  31. aclientp-0.1.0/src/aclientp/bridge/ws_server_cli.py +89 -0
  32. aclientp-0.1.0/src/aclientp/client/__init__.py +7 -0
  33. aclientp-0.1.0/src/aclientp/client/connection.py +341 -0
  34. aclientp-0.1.0/src/aclientp/client/implementations/__init__.py +7 -0
  35. aclientp-0.1.0/src/aclientp/client/implementations/default_client.py +198 -0
  36. aclientp-0.1.0/src/aclientp/client/implementations/headless_client.py +274 -0
  37. aclientp-0.1.0/src/aclientp/client/implementations/noop_client.py +122 -0
  38. aclientp-0.1.0/src/aclientp/client/protocol.py +93 -0
  39. aclientp-0.1.0/src/aclientp/connection.py +494 -0
  40. aclientp-0.1.0/src/aclientp/exceptions.py +78 -0
  41. aclientp-0.1.0/src/aclientp/filesystem.py +567 -0
  42. aclientp-0.1.0/src/aclientp/py.typed +0 -0
  43. aclientp-0.1.0/src/aclientp/registry/__init__.py +29 -0
  44. aclientp-0.1.0/src/aclientp/registry/archive.py +61 -0
  45. aclientp-0.1.0/src/aclientp/registry/fetch.py +72 -0
  46. aclientp-0.1.0/src/aclientp/registry/model.py +150 -0
  47. aclientp-0.1.0/src/aclientp/registry/prepare.py +90 -0
  48. aclientp-0.1.0/src/aclientp/router.py +116 -0
  49. aclientp-0.1.0/src/aclientp/schema/__init__.py +591 -0
  50. aclientp-0.1.0/src/aclientp/schema/agent_plan.py +68 -0
  51. aclientp-0.1.0/src/aclientp/schema/agent_requests.py +130 -0
  52. aclientp-0.1.0/src/aclientp/schema/agent_responses.py +339 -0
  53. aclientp-0.1.0/src/aclientp/schema/base.py +39 -0
  54. aclientp-0.1.0/src/aclientp/schema/capabilities.py +448 -0
  55. aclientp-0.1.0/src/aclientp/schema/client_requests.py +442 -0
  56. aclientp-0.1.0/src/aclientp/schema/client_responses.py +100 -0
  57. aclientp-0.1.0/src/aclientp/schema/common.py +177 -0
  58. aclientp-0.1.0/src/aclientp/schema/config_options.py +184 -0
  59. aclientp-0.1.0/src/aclientp/schema/content_blocks.py +186 -0
  60. aclientp-0.1.0/src/aclientp/schema/cursors.py +144 -0
  61. aclientp-0.1.0/src/aclientp/schema/elicitation.py +406 -0
  62. aclientp-0.1.0/src/aclientp/schema/field_meta.py +598 -0
  63. aclientp-0.1.0/src/aclientp/schema/mcp.py +173 -0
  64. aclientp-0.1.0/src/aclientp/schema/messages.py +196 -0
  65. aclientp-0.1.0/src/aclientp/schema/notifications.py +112 -0
  66. aclientp-0.1.0/src/aclientp/schema/protocol_stuff.md +3 -0
  67. aclientp-0.1.0/src/aclientp/schema/providers.py +89 -0
  68. aclientp-0.1.0/src/aclientp/schema/proxy.py +49 -0
  69. aclientp-0.1.0/src/aclientp/schema/session_state.py +72 -0
  70. aclientp-0.1.0/src/aclientp/schema/session_updates.py +778 -0
  71. aclientp-0.1.0/src/aclientp/schema/slash_commands.py +51 -0
  72. aclientp-0.1.0/src/aclientp/schema/terminal.py +15 -0
  73. aclientp-0.1.0/src/aclientp/schema/tool_call.py +373 -0
  74. aclientp-0.1.0/src/aclientp/schema/v2/__init__.py +774 -0
  75. aclientp-0.1.0/src/aclientp/schema/v2/auth.py +160 -0
  76. aclientp-0.1.0/src/aclientp/schema/v2/base.py +99 -0
  77. aclientp-0.1.0/src/aclientp/schema/v2/capabilities.py +280 -0
  78. aclientp-0.1.0/src/aclientp/schema/v2/commands.py +89 -0
  79. aclientp-0.1.0/src/aclientp/schema/v2/common.py +252 -0
  80. aclientp-0.1.0/src/aclientp/schema/v2/config_options.py +218 -0
  81. aclientp-0.1.0/src/aclientp/schema/v2/content.py +169 -0
  82. aclientp-0.1.0/src/aclientp/schema/v2/cursors.py +148 -0
  83. aclientp-0.1.0/src/aclientp/schema/v2/elicitation.py +345 -0
  84. aclientp-0.1.0/src/aclientp/schema/v2/initialize.py +43 -0
  85. aclientp-0.1.0/src/aclientp/schema/v2/mcp.py +154 -0
  86. aclientp-0.1.0/src/aclientp/schema/v2/messages.py +119 -0
  87. aclientp-0.1.0/src/aclientp/schema/v2/permissions.py +142 -0
  88. aclientp-0.1.0/src/aclientp/schema/v2/plans.py +95 -0
  89. aclientp-0.1.0/src/aclientp/schema/v2/prompt.py +179 -0
  90. aclientp-0.1.0/src/aclientp/schema/v2/protocol.py +342 -0
  91. aclientp-0.1.0/src/aclientp/schema/v2/providers.py +86 -0
  92. aclientp-0.1.0/src/aclientp/schema/v2/session_updates.py +316 -0
  93. aclientp-0.1.0/src/aclientp/schema/v2/sessions.py +353 -0
  94. aclientp-0.1.0/src/aclientp/schema/v2/subagents.py +61 -0
  95. aclientp-0.1.0/src/aclientp/schema/v2/terminals.py +139 -0
  96. aclientp-0.1.0/src/aclientp/schema/v2/tool_calls.py +304 -0
  97. aclientp-0.1.0/src/aclientp/schema_reference.py +1060 -0
  98. aclientp-0.1.0/src/aclientp/stdio.py +261 -0
  99. aclientp-0.1.0/src/aclientp/task/__init__.py +59 -0
  100. aclientp-0.1.0/src/aclientp/task/debug.py +187 -0
  101. aclientp-0.1.0/src/aclientp/task/dispatcher.py +107 -0
  102. aclientp-0.1.0/src/aclientp/task/queue.py +69 -0
  103. aclientp-0.1.0/src/aclientp/task/sender.py +166 -0
  104. aclientp-0.1.0/src/aclientp/task/state.py +91 -0
  105. aclientp-0.1.0/src/aclientp/task/supervisor.py +98 -0
  106. aclientp-0.1.0/src/aclientp/terminal_handle.py +30 -0
  107. aclientp-0.1.0/src/aclientp/tool_call_reporter.py +193 -0
  108. aclientp-0.1.0/src/aclientp/tool_call_state.py +175 -0
  109. aclientp-0.1.0/src/aclientp/transports.py +445 -0
  110. aclientp-0.1.0/src/aclientp/v2/__init__.py +1 -0
  111. aclientp-0.1.0/src/aclientp/v2/agent.py +448 -0
  112. aclientp-0.1.0/src/aclientp/v2/client.py +356 -0
aclientp-0.1.0/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024, Philipp Temminghoff
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: aclientp
3
+ Version: 0.1.0
4
+ Summary: Agent Client Protocol (ACP) for Python: typed v1 and draft v2, checked against the upstream schema
5
+ Keywords: acp,agent-client-protocol,agents,ai,json-rpc,llm,zed
6
+ Author: Philipp Temminghoff
7
+ Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Framework :: Pydantic
12
+ Classifier: Framework :: Pydantic :: 2
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Classifier: Typing :: Typed
22
+ Requires-Dist: anyenv>=2.0.17
23
+ Requires-Dist: anyio>=4.0
24
+ Requires-Dist: httpx>=0.28
25
+ Requires-Dist: pydantic>=2.14
26
+ Requires-Dist: structlog>=25.0
27
+ Requires-Dist: upathtools>=1.20
28
+ Requires-Dist: starlette ; extra == 'bridge'
29
+ Requires-Dist: uvicorn ; extra == 'bridge'
30
+ Requires-Dist: websockets ; extra == 'bridge'
31
+ Requires-Dist: fastapi ; extra == 'debug'
32
+ Requires-Dist: uvicorn ; extra == 'debug'
33
+ Requires-Dist: logfire ; extra == 'tracing'
34
+ Requires-Dist: websockets ; extra == 'websocket'
35
+ Requires-Python: >=3.13
36
+ Project-URL: Code coverage, https://app.codecov.io/gh/phil65/aclientp
37
+ Project-URL: Discussions, https://github.com/phil65/aclientp/discussions
38
+ Project-URL: Documentation, https://phil65.github.io/aclientp/
39
+ Project-URL: Issues, https://github.com/phil65/aclientp/issues
40
+ Project-URL: Source, https://github.com/phil65/aclientp
41
+ Provides-Extra: bridge
42
+ Provides-Extra: debug
43
+ Provides-Extra: tracing
44
+ Provides-Extra: websocket
45
+ Description-Content-Type: text/markdown
46
+
47
+ # AClientP
48
+
49
+ [![PyPI License](https://img.shields.io/pypi/l/aclientp.svg)](https://pypi.org/project/aclientp/)
50
+ [![Package status](https://img.shields.io/pypi/status/aclientp.svg)](https://pypi.org/project/aclientp/)
51
+ [![Monthly downloads](https://img.shields.io/pypi/dm/aclientp.svg)](https://pypi.org/project/aclientp/)
52
+ [![Distribution format](https://img.shields.io/pypi/format/aclientp.svg)](https://pypi.org/project/aclientp/)
53
+ [![Wheel availability](https://img.shields.io/pypi/wheel/aclientp.svg)](https://pypi.org/project/aclientp/)
54
+ [![Python version](https://img.shields.io/pypi/pyversions/aclientp.svg)](https://pypi.org/project/aclientp/)
55
+ [![Implementation](https://img.shields.io/pypi/implementation/aclientp.svg)](https://pypi.org/project/aclientp/)
56
+ [![Releases](https://img.shields.io/github/downloads/phil65/aclientp/total.svg)](https://github.com/phil65/aclientp/releases)
57
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/aclientp)](https://github.com/phil65/aclientp/graphs/contributors)
58
+ [![Github Discussions](https://img.shields.io/github/discussions/phil65/aclientp)](https://github.com/phil65/aclientp/discussions)
59
+ [![Github Forks](https://img.shields.io/github/forks/phil65/aclientp)](https://github.com/phil65/aclientp/forks)
60
+ [![Github Issues](https://img.shields.io/github/issues/phil65/aclientp)](https://github.com/phil65/aclientp/issues)
61
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/aclientp)](https://github.com/phil65/aclientp/pulls)
62
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/aclientp)](https://github.com/phil65/aclientp/watchers)
63
+ [![Github Stars](https://img.shields.io/github/stars/phil65/aclientp)](https://github.com/phil65/aclientp/stars)
64
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/aclientp)](https://github.com/phil65/aclientp)
65
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/aclientp)](https://github.com/phil65/aclientp/commits)
66
+ [![Github release date](https://img.shields.io/github/release-date/phil65/aclientp)](https://github.com/phil65/aclientp/releases)
67
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/aclientp)](https://github.com/phil65/aclientp)
68
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/aclientp)](https://github.com/phil65/aclientp)
69
+ [![Package status](https://codecov.io/gh/phil65/aclientp/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/aclientp/)
70
+ [![PyUp](https://pyup.io/repos/github/phil65/aclientp/shield.svg)](https://pyup.io/repos/github/phil65/aclientp/)
71
+
72
+ [Read the documentation!](https://phil65.github.io/aclientp/)
73
+
74
+ **AClientP** implements the [Agent Client Protocol](https://agentclientprotocol.com)
75
+ (ACP, the protocol between code editors and AI coding agents) in typed Python: both
76
+ the agent and the client side, for the released **v1** protocol and the **draft v2**.
77
+
78
+ The name sets it apart from the other "ACP"s (Agent Communication Protocol,
79
+ Agent Connect Protocol, Agentic Commerce Protocol): **a**gent **client** **p**rotocol.
80
+
81
+ ## Why another ACP library?
82
+
83
+ - **Checked against upstream.** The models are hand-written, but every release pins
84
+ an upstream schema release (`schema/v1`, `schema/v2`) and a conformance check
85
+ compares the models with it: fields, required/optional, nullability, limits, enums,
86
+ union variants and methods. Known differences are documented with a reason.
87
+ - **v1 and v2.** v2 lives next to v1 (`aclientp.schema.v2`, `aclientp.v2`), and
88
+ `RoutedAgentConnection` serves a client with the v1 or v2 agent, chosen by its
89
+ `initialize` request, like the official TypeScript SDK's router.
90
+ - **Typed throughout.** Pydantic models, `mypy --strict`, discriminated unions with
91
+ fallback variants that keep unknown fields (so custom and future messages survive a
92
+ round trip).
93
+ - **Small core.** pydantic, anyio, anyenv, httpx, structlog and upathtools; web
94
+ servers, WebSockets and tracing are extras.
95
+
96
+ ## Installation
97
+
98
+ ```bash
99
+ uv add aclientp
100
+ ```
101
+
102
+ | Extra | Adds |
103
+ | --- | --- |
104
+ | `websocket` | WebSocket transport |
105
+ | `bridge` | `aclientp-bridge`: expose a stdio agent over HTTP / WebSocket |
106
+ | `debug` | `aclientp-debug-server`: a mock agent with a web UI |
107
+ | `tracing` | logfire spans for handled requests |
108
+
109
+ ## Quick start
110
+
111
+ ### A v1 agent over stdio
112
+
113
+ ```python
114
+ import anyio
115
+
116
+ from aclientp import Agent, run_agent
117
+ from aclientp.schema import (
118
+ InitializeRequest,
119
+ InitializeResponse,
120
+ NewSessionRequest,
121
+ NewSessionResponse,
122
+ PromptRequest,
123
+ PromptResponse,
124
+ )
125
+
126
+
127
+ class EchoAgent(Agent):
128
+ async def initialize(self, params: InitializeRequest) -> InitializeResponse:
129
+ return InitializeResponse(protocol_version=1)
130
+
131
+ async def new_session(self, params: NewSessionRequest) -> NewSessionResponse:
132
+ return NewSessionResponse(session_id="session-1")
133
+
134
+ async def prompt(self, params: PromptRequest) -> PromptResponse:
135
+ return PromptResponse(stop_reason="end_turn")
136
+
137
+
138
+ anyio.run(run_agent, EchoAgent())
139
+ ```
140
+
141
+ ### Serving v1 and v2
142
+
143
+ ```python
144
+ from aclientp.router import RoutedAgentConnection
145
+ from aclientp.stdio import stdio_streams
146
+
147
+
148
+ async def main() -> None:
149
+ stdin, stdout = await stdio_streams()
150
+ conn = RoutedAgentConnection(stdout, stdin, v1=MyV1Agent(), v2=MyV2Agent)
151
+ await conn.wait_closed()
152
+ ```
153
+
154
+ A v2 agent subclasses `aclientp.v2.agent.Agent` and overrides the methods it supports;
155
+ the rest answer `-32601`. v2 models follow the v2 patch rules: optional fields default
156
+ to `MISSING` and are left out, `None` is sent as `null`. Serialize with `to_wire` and
157
+ test fields with `is_set` (`MISSING` is truthy).
158
+
159
+ ## Staying in sync with upstream
160
+
161
+ ```bash
162
+ uv run python -m aclientp.schema_reference latest # pinned vs newest tag
163
+ uv run python -m aclientp.schema_reference sync --dry-run # changelog of the newest tag
164
+ uv run python -m aclientp.schema_reference sync # pin it
165
+ uv run python -m aclientp.schema_reference check # models vs pinned schema
166
+ uv run python -m aclientp.schema_reference refs # changes in reference implementations
167
+ ```
168
+
169
+ Use `--protocol 2` for v2. `schema/<version>/conformance.toml` lists renames and known
170
+ differences; the test suite runs the same check, so undocumented drift fails CI.
171
+ `schema/references.toml` pins reference implementations (the official TypeScript SDK
172
+ and claude-agent-acp) by commit; `refs` lists the upstream commits since each pin with
173
+ a compare link.
174
+
175
+ ## Status
176
+
177
+ v1 follows `schema-v1.33.0`, v2 follows the draft `schema-v2.0.0-alpha.17`. The v2
178
+ API is **unstable** and follows the draft as it changes.
@@ -0,0 +1,132 @@
1
+ # AClientP
2
+
3
+ [![PyPI License](https://img.shields.io/pypi/l/aclientp.svg)](https://pypi.org/project/aclientp/)
4
+ [![Package status](https://img.shields.io/pypi/status/aclientp.svg)](https://pypi.org/project/aclientp/)
5
+ [![Monthly downloads](https://img.shields.io/pypi/dm/aclientp.svg)](https://pypi.org/project/aclientp/)
6
+ [![Distribution format](https://img.shields.io/pypi/format/aclientp.svg)](https://pypi.org/project/aclientp/)
7
+ [![Wheel availability](https://img.shields.io/pypi/wheel/aclientp.svg)](https://pypi.org/project/aclientp/)
8
+ [![Python version](https://img.shields.io/pypi/pyversions/aclientp.svg)](https://pypi.org/project/aclientp/)
9
+ [![Implementation](https://img.shields.io/pypi/implementation/aclientp.svg)](https://pypi.org/project/aclientp/)
10
+ [![Releases](https://img.shields.io/github/downloads/phil65/aclientp/total.svg)](https://github.com/phil65/aclientp/releases)
11
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/aclientp)](https://github.com/phil65/aclientp/graphs/contributors)
12
+ [![Github Discussions](https://img.shields.io/github/discussions/phil65/aclientp)](https://github.com/phil65/aclientp/discussions)
13
+ [![Github Forks](https://img.shields.io/github/forks/phil65/aclientp)](https://github.com/phil65/aclientp/forks)
14
+ [![Github Issues](https://img.shields.io/github/issues/phil65/aclientp)](https://github.com/phil65/aclientp/issues)
15
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/aclientp)](https://github.com/phil65/aclientp/pulls)
16
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/aclientp)](https://github.com/phil65/aclientp/watchers)
17
+ [![Github Stars](https://img.shields.io/github/stars/phil65/aclientp)](https://github.com/phil65/aclientp/stars)
18
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/aclientp)](https://github.com/phil65/aclientp)
19
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/aclientp)](https://github.com/phil65/aclientp/commits)
20
+ [![Github release date](https://img.shields.io/github/release-date/phil65/aclientp)](https://github.com/phil65/aclientp/releases)
21
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/aclientp)](https://github.com/phil65/aclientp)
22
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/aclientp)](https://github.com/phil65/aclientp)
23
+ [![Package status](https://codecov.io/gh/phil65/aclientp/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/aclientp/)
24
+ [![PyUp](https://pyup.io/repos/github/phil65/aclientp/shield.svg)](https://pyup.io/repos/github/phil65/aclientp/)
25
+
26
+ [Read the documentation!](https://phil65.github.io/aclientp/)
27
+
28
+ **AClientP** implements the [Agent Client Protocol](https://agentclientprotocol.com)
29
+ (ACP, the protocol between code editors and AI coding agents) in typed Python: both
30
+ the agent and the client side, for the released **v1** protocol and the **draft v2**.
31
+
32
+ The name sets it apart from the other "ACP"s (Agent Communication Protocol,
33
+ Agent Connect Protocol, Agentic Commerce Protocol): **a**gent **client** **p**rotocol.
34
+
35
+ ## Why another ACP library?
36
+
37
+ - **Checked against upstream.** The models are hand-written, but every release pins
38
+ an upstream schema release (`schema/v1`, `schema/v2`) and a conformance check
39
+ compares the models with it: fields, required/optional, nullability, limits, enums,
40
+ union variants and methods. Known differences are documented with a reason.
41
+ - **v1 and v2.** v2 lives next to v1 (`aclientp.schema.v2`, `aclientp.v2`), and
42
+ `RoutedAgentConnection` serves a client with the v1 or v2 agent, chosen by its
43
+ `initialize` request, like the official TypeScript SDK's router.
44
+ - **Typed throughout.** Pydantic models, `mypy --strict`, discriminated unions with
45
+ fallback variants that keep unknown fields (so custom and future messages survive a
46
+ round trip).
47
+ - **Small core.** pydantic, anyio, anyenv, httpx, structlog and upathtools; web
48
+ servers, WebSockets and tracing are extras.
49
+
50
+ ## Installation
51
+
52
+ ```bash
53
+ uv add aclientp
54
+ ```
55
+
56
+ | Extra | Adds |
57
+ | --- | --- |
58
+ | `websocket` | WebSocket transport |
59
+ | `bridge` | `aclientp-bridge`: expose a stdio agent over HTTP / WebSocket |
60
+ | `debug` | `aclientp-debug-server`: a mock agent with a web UI |
61
+ | `tracing` | logfire spans for handled requests |
62
+
63
+ ## Quick start
64
+
65
+ ### A v1 agent over stdio
66
+
67
+ ```python
68
+ import anyio
69
+
70
+ from aclientp import Agent, run_agent
71
+ from aclientp.schema import (
72
+ InitializeRequest,
73
+ InitializeResponse,
74
+ NewSessionRequest,
75
+ NewSessionResponse,
76
+ PromptRequest,
77
+ PromptResponse,
78
+ )
79
+
80
+
81
+ class EchoAgent(Agent):
82
+ async def initialize(self, params: InitializeRequest) -> InitializeResponse:
83
+ return InitializeResponse(protocol_version=1)
84
+
85
+ async def new_session(self, params: NewSessionRequest) -> NewSessionResponse:
86
+ return NewSessionResponse(session_id="session-1")
87
+
88
+ async def prompt(self, params: PromptRequest) -> PromptResponse:
89
+ return PromptResponse(stop_reason="end_turn")
90
+
91
+
92
+ anyio.run(run_agent, EchoAgent())
93
+ ```
94
+
95
+ ### Serving v1 and v2
96
+
97
+ ```python
98
+ from aclientp.router import RoutedAgentConnection
99
+ from aclientp.stdio import stdio_streams
100
+
101
+
102
+ async def main() -> None:
103
+ stdin, stdout = await stdio_streams()
104
+ conn = RoutedAgentConnection(stdout, stdin, v1=MyV1Agent(), v2=MyV2Agent)
105
+ await conn.wait_closed()
106
+ ```
107
+
108
+ A v2 agent subclasses `aclientp.v2.agent.Agent` and overrides the methods it supports;
109
+ the rest answer `-32601`. v2 models follow the v2 patch rules: optional fields default
110
+ to `MISSING` and are left out, `None` is sent as `null`. Serialize with `to_wire` and
111
+ test fields with `is_set` (`MISSING` is truthy).
112
+
113
+ ## Staying in sync with upstream
114
+
115
+ ```bash
116
+ uv run python -m aclientp.schema_reference latest # pinned vs newest tag
117
+ uv run python -m aclientp.schema_reference sync --dry-run # changelog of the newest tag
118
+ uv run python -m aclientp.schema_reference sync # pin it
119
+ uv run python -m aclientp.schema_reference check # models vs pinned schema
120
+ uv run python -m aclientp.schema_reference refs # changes in reference implementations
121
+ ```
122
+
123
+ Use `--protocol 2` for v2. `schema/<version>/conformance.toml` lists renames and known
124
+ differences; the test suite runs the same check, so undocumented drift fails CI.
125
+ `schema/references.toml` pins reference implementations (the official TypeScript SDK
126
+ and claude-agent-acp) by commit; `refs` lists the upstream commits since each pin with
127
+ a compare link.
128
+
129
+ ## Status
130
+
131
+ v1 follows `schema-v1.33.0`, v2 follows the draft `schema-v2.0.0-alpha.17`. The v2
132
+ API is **unstable** and follows the draft as it changes.
@@ -0,0 +1,345 @@
1
+ [project]
2
+ name = "aclientp"
3
+ version = "0.1.0"
4
+ description = "Agent Client Protocol (ACP) for Python: typed v1 and draft v2, checked against the upstream schema"
5
+ readme = "README.md"
6
+ requires-python = ">=3.13"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ keywords = [
10
+ "acp",
11
+ "agent-client-protocol",
12
+ "agents",
13
+ "ai",
14
+ "json-rpc",
15
+ "llm",
16
+ "zed",
17
+ ]
18
+ classifiers = [
19
+ "Development Status :: 4 - Beta",
20
+ "Framework :: Pydantic",
21
+ "Framework :: Pydantic :: 2",
22
+ "Intended Audience :: Developers",
23
+ "Operating System :: OS Independent",
24
+ "Programming Language :: Python :: 3",
25
+ "Programming Language :: Python :: 3 :: Only",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Programming Language :: Python :: 3.14",
28
+ "Topic :: Software Development",
29
+ "Topic :: Software Development :: Libraries :: Python Modules",
30
+ "Typing :: Typed",
31
+ ]
32
+ dependencies = [
33
+ "anyenv>=2.0.17",
34
+ "anyio>=4.0",
35
+ "httpx>=0.28",
36
+ "pydantic>=2.14",
37
+ "structlog>=25.0",
38
+ "upathtools>=1.20",
39
+ ]
40
+
41
+ [[project.authors]]
42
+ name = "Philipp Temminghoff"
43
+ email = "philipptemminghoff@googlemail.com"
44
+
45
+ [project.optional-dependencies]
46
+ bridge = [
47
+ "starlette",
48
+ "uvicorn",
49
+ "websockets",
50
+ ]
51
+ debug = [
52
+ "fastapi",
53
+ "uvicorn",
54
+ ]
55
+ tracing = ["logfire"]
56
+ websocket = ["websockets"]
57
+
58
+ [project.scripts]
59
+ aclientp-bridge = "aclientp.bridge.__main__:main"
60
+ aclientp-debug-server = "aclientp.agent.implementations.debug_server.cli:main"
61
+
62
+ [project.entry-points."fsspec.specs"]
63
+ acp = "aclientp.filesystem:ACPFileSystem"
64
+
65
+ [project.entry-points."universal_pathlib.implementations"]
66
+ acp = "aclientp.filesystem:ACPPath"
67
+
68
+ [project.urls]
69
+ "Code coverage" = "https://app.codecov.io/gh/phil65/aclientp"
70
+ Discussions = "https://github.com/phil65/aclientp/discussions"
71
+ Documentation = "https://phil65.github.io/aclientp/"
72
+ Issues = "https://github.com/phil65/aclientp/issues"
73
+ Source = "https://github.com/phil65/aclientp"
74
+
75
+ [dependency-groups]
76
+ dev = [
77
+ "devtools",
78
+ "pyreadline3",
79
+ "pytest",
80
+ "pytest-cov",
81
+ "pytest-asyncio",
82
+ "pytest-timeout",
83
+ ]
84
+ benchmark = ["pyinstrument"]
85
+ docs = [
86
+ "mkdocs-material",
87
+ "mkdocs-mknodes",
88
+ ]
89
+ lint = [
90
+ "mypy; python_version >= '3.14'",
91
+ "mypy[faster-cache]; python_version < '3.14'",
92
+ "ruff",
93
+ ]
94
+
95
+ [build-system]
96
+ requires = ["uv_build>=0.8.22"]
97
+ build-backend = "uv_build"
98
+
99
+ [tool.coverage.report]
100
+ exclude_lines = [
101
+ "pragma: no cover",
102
+ "if TYPE_CHECKING:",
103
+ "@overload",
104
+ "except ImportError",
105
+ 'if __name__ == "__main__":',
106
+ ]
107
+
108
+ [tool.mknodes]
109
+ allowed-commit-types = [
110
+ "fix",
111
+ "feat",
112
+ "refactor",
113
+ "docs",
114
+ "test",
115
+ "build",
116
+ "chore",
117
+ ]
118
+ docstring-style = "google"
119
+
120
+ [tool.mypy]
121
+ python_version = "3.13"
122
+ pretty = true
123
+ strict = true
124
+ check_untyped_defs = true
125
+ exclude = [
126
+ "venv/",
127
+ ".venv/",
128
+ ]
129
+ plugins = ["pydantic.mypy"]
130
+ warn_return_any = true
131
+ warn_unused_configs = true
132
+ disallow_untyped_defs = true
133
+ disallow_incomplete_defs = true
134
+ disallow_untyped_decorators = true
135
+ no_implicit_optional = true
136
+ warn_redundant_casts = true
137
+ warn_unused_ignores = true
138
+ warn_no_return = true
139
+ strict_equality = true
140
+
141
+ [[tool.mypy.overrides]]
142
+ module = "tests.*"
143
+ disallow_untyped_defs = false
144
+ disallow_untyped_calls = false
145
+ disallow_incomplete_defs = false
146
+ disable_error_code = [
147
+ "no-untyped-def",
148
+ "no-untyped-call",
149
+ "no-any-return",
150
+ "unused-ignore",
151
+ ]
152
+
153
+ [[tool.mypy.overrides]]
154
+ module = ["fsspec.*"]
155
+ ignore_missing_imports = true
156
+
157
+ [tool.pyright]
158
+ venvPath = "."
159
+ venv = ".venv"
160
+ pythonVersion = "3.13"
161
+ pythonPlatform = "All"
162
+ typeCheckingMode = "basic"
163
+ deprecateTypingAliases = true
164
+ reportMissingTypeStubs = false
165
+ reportUnusedCallResult = false
166
+ reportUnknownVariableType = false
167
+ reportAny = false
168
+ reportImplicitOverride = false
169
+ reportUnusedFunction = false
170
+ reportImplicitStringConcatenation = false
171
+ reportIgnoreCommentWithoutRule = false
172
+ reportUnannotatedClassAttribute = false
173
+ reportSelfClsParameterName = false
174
+ reportPrivateImportUsage = false
175
+
176
+ [tool.pytest]
177
+ log_cli = true
178
+ log_date_format = "%Y-%m-%d %H:%M:%S"
179
+ log_format = "%(asctime)s %(levelname)s %(message)s"
180
+ minversion = "9.0"
181
+ testpaths = ["tests/"]
182
+ asyncio_mode = "auto"
183
+ asyncio_default_fixture_loop_scope = "function"
184
+ timeout = "60"
185
+
186
+ [tool.ruff]
187
+ line-length = 100
188
+ extend-exclude = ["docs"]
189
+ target-version = "py313"
190
+
191
+ [tool.ruff.lint]
192
+ future-annotations = true
193
+ select = [
194
+ "A",
195
+ "B",
196
+ "BLE",
197
+ "C",
198
+ "C4",
199
+ "COM",
200
+ "D",
201
+ "E",
202
+ "EM",
203
+ "EXE",
204
+ "F",
205
+ "FA",
206
+ "FLY",
207
+ "G",
208
+ "I",
209
+ "ICN",
210
+ "INP",
211
+ "INT",
212
+ "ISC",
213
+ "N",
214
+ "PERF",
215
+ "PIE",
216
+ "PLE",
217
+ "PLC",
218
+ "PLR",
219
+ "PT",
220
+ "PTH",
221
+ "PYI",
222
+ "Q",
223
+ "RET",
224
+ "RSE",
225
+ "RUF",
226
+ "SIM",
227
+ "SLF",
228
+ "SLOT",
229
+ "T10",
230
+ "TC",
231
+ "TID",
232
+ "TRY",
233
+ "UP",
234
+ "W",
235
+ "YTT",
236
+ ]
237
+ ignore = [
238
+ "C408",
239
+ "B905",
240
+ "C901",
241
+ "COM812",
242
+ "D100",
243
+ "D101",
244
+ "D102",
245
+ "D103",
246
+ "D104",
247
+ "D105",
248
+ "D106",
249
+ "D107",
250
+ "D203",
251
+ "D204",
252
+ "D213",
253
+ "D215",
254
+ "D400",
255
+ "D401",
256
+ "D404",
257
+ "D406",
258
+ "D407",
259
+ "D408",
260
+ "D409",
261
+ "D413",
262
+ "EM101",
263
+ "EM102",
264
+ "ISC001",
265
+ "PLC0415",
266
+ "PLR0912",
267
+ "PLR0913",
268
+ "PLR0915",
269
+ "SLF001",
270
+ "TRY003",
271
+ "TC006",
272
+ "PLR0917",
273
+ ]
274
+
275
+ [tool.ruff.lint.flake8-quotes]
276
+ docstring-quotes = "double"
277
+
278
+ [tool.ruff.lint.flake8-type-checking]
279
+ runtime-evaluated-base-classes = [
280
+ "pydantic.BaseModel",
281
+ "sqlalchemy.orm.DeclarativeBase",
282
+ "schemez.Schema",
283
+ "sqlmodel.SQLModel",
284
+ "aclientp.schema.base.Schema",
285
+ "aclientp.schema.v2.base.Schema",
286
+ ]
287
+ runtime-evaluated-decorators = [
288
+ "pydantic.validate_call",
289
+ "fastapi.FastAPI.get",
290
+ "fastapi.FastAPI.post",
291
+ "fastmcp.FastMCP.tool",
292
+ "typer.Typer.command",
293
+ ]
294
+
295
+ [tool.ruff.lint.isort]
296
+ lines-after-imports = 2
297
+ force-sort-within-sections = true
298
+ combine-as-imports = true
299
+
300
+ [tool.ruff.lint.mccabe]
301
+ max-complexity = 15
302
+
303
+ [tool.ruff.lint.per-file-ignores]
304
+ "__init__.py" = [
305
+ "E402",
306
+ "I001",
307
+ ]
308
+ "src/aclientp/schema/*" = ["PYI051"]
309
+ "scripts/*" = ["INP001"]
310
+ "*tests/*" = [
311
+ "D100",
312
+ "PLR2004",
313
+ ]
314
+
315
+ [tool.ruff.format]
316
+ preview = true
317
+
318
+ [tool.ty.environment]
319
+ python-version = "3.13"
320
+ python-platform = "all"
321
+
322
+ [tool.uv]
323
+ default-groups = [
324
+ "dev",
325
+ "lint",
326
+ "docs",
327
+ ]
328
+
329
+ [tool.uv.build-backend]
330
+ wheel-exclude = [
331
+ ".mypy_cache/**",
332
+ "__pycache__/**",
333
+ "*.pyc",
334
+ "*.pyo",
335
+ ".pytest_cache/**",
336
+ ".ruff_cache/**",
337
+ ]
338
+ source-exclude = [
339
+ ".mypy_cache/**",
340
+ "__pycache__/**",
341
+ "*.pyc",
342
+ "*.pyo",
343
+ ".pytest_cache/**",
344
+ ".ruff_cache/**",
345
+ ]