feat: Refactor the API to expose less types users need to import

[frostming]

Problem statement

Taking from the quick start example:

import asyncio
import sys
from pathlib import Path

from acp import spawn_agent_process, text_block
from acp.interfaces import Client
from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, SessionNotification


class SimpleClient(Client):
 async def requestPermission(self, params): # pragma: no cover - minimal stub
 return {"outcome": {"outcome": "cancelled"}}

 async def sessionUpdate(self, params: SessionNotification) -> None:
 print("update:", params.sessionId, params.update)


async def main() -> None:
 script = Path("examples/echo_agent.py")
 async with spawn_agent_process(lambda _agent: SimpleClient(), sys.executable, str(script)) as (conn, _proc):
 await conn.initialize(InitializeRequest(protocolVersion=1))
 session = await conn.newSession(NewSessionRequest(cwd=str(script.parent), mcpServers=[]))
 await conn.prompt(
 PromptRequest(
 sessionId=session.sessionId,
 prompt=[text_block("Hello from spawn!")],
 )
 )

asyncio.run(main())

connection.initialize takes a single parameter with a set fields defined, and users have to import that InitializeRequest to construct it. Same as connection.newSession() method.

It can be easily changed to the following API style:

connection.initialize(protocol_version=1)

(snake_case is also preferred)

Proposed solution

While this is a breaking change, we can add a compatibility layer on such methods, something like below:

@compat_params(InitializeRequest)
async def initialize(self, protocol_version: int) -> InitializeResponse:
 return await request_model(
 self._conn,
 AGENT_METHODS["initialize"],
 InitializeRequest(protocolVersion=protocol_version),
 InitializeResponse,
 )

Alternatives considered

If it's not easy to do over the codebase, in the worst case, we can add a acp._next package with the new APIs, and export all members in acp/__init__.py with proper deprecation warnings.

Additional context

No response

Can you help build it?

• I can contribute code or docs for this request.

[PsiACE]

I believe we are about to embark on a truly Pythonic beginning. 🤗

[frostming]

Here are some to-do items I’ve broken down.

• Change auto-generated pydantic model fields to be snake cased feat: change field names to snake case #31
• Auto-generate the method signatures of clients and agents from the schema feat: Auto-generate agent/client methods based on the schema #36
• Improve some of the APIs to be more Pythonic, such as avoiding lambdas in Agent intialization. feat: Redesign the APIs to be more intuitive, and make them backward-compatible #37
• Maybe add a backward-compatibility layer with deprecation warning feat: Redesign the APIs to be more intuitive, and make them backward-compatible #37

[phil65]

Feel free to steal code from my fork:
https://github.com/phil65/llmling-agent/tree/main/src/acp

I already added quite a lot of "pythonicness" (session.notification + session.requests helper classes for example), and also switched to a handcrafted schema definition (its not worth it to auto-generate the schema classes, you spend more time adjusting the generation code than just adjusting the schema manually)

[frostming]

Feel free to steal code from my fork: https://github.com/phil65/llmling-agent/tree/main/src/acp

I already added quite a lot of "pythonicness" (session.notification + session.requests helper classes for example), and also switched to a handcrafted schema definition (its not worth it to auto-generate the schema classes, you spend more time adjusting the generation code than just adjusting the schema manually)

Thanks for the code; it’s good to read. I think your point makes sense—we can remove the auto-generated code anytime we feel overwhelmed maintaining it and switch to a handcrafted schema.

[phil65]

oh, and for @frostming , I see that you dabble a lot with OpenDAL, I also added a quick shot for an FSSpec ACP filesystem to operate client-side. perhaps its interesting for you. (only did some basic testing yet though)
https://github.com/phil65/llmling-agent/blob/main/src/acp/filesystem.py

[PsiACE]

Most of the points in #30 are already addressed in the 0.7.x branch — huge thanks to @frostming for the exceptional work and for keeping everything compatible. I suggest we close this issue, and I’ll open a [DNM] PR for 0.7.x so we can start reviewing the upcoming changes.