Metadata-Version: 2.5
Name: api-mapper-client
Version: 1.2.0
Summary: Client SDK for the CodedProjects AI ApiMapper Runtime
Project-URL: Homepage, https://apimapper.ai
Author: Coded Projects
License-Expression: MIT
License-File: LICENSE
Keywords: ai,apimapper,client,llm,mcp,python,sdk,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: httpx>=2.12.0
Provides-Extra: all
Requires-Dist: langchain-core>=1.3.3; extra == 'all'
Requires-Dist: langgraph>=1.0.10; extra == 'all'
Requires-Dist: pydantic>=2.4.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
Requires-Dist: pydantic>=2.4.0; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langchain-core>=1.3.3; extra == 'langgraph'
Requires-Dist: langgraph>=1.0.10; extra == 'langgraph'
Requires-Dist: pydantic>=2.4.0; extra == 'langgraph'
Description-Content-Type: text/markdown

# api-mapper-client

Python SDK for discovering and invoking AI ApiMapper Runtime tools from Python applications and agents.

## Install

```bash
pip install api-mapper-client
```

Optional integrations:

```bash
pip install "api-mapper-client[langchain]"
pip install "api-mapper-client[langgraph]"
pip install "api-mapper-client[all]"
```

## What it provides

- runtime tool discovery,
- runtime system prompt loading,
- tool invocation over MCP-compatible HTTP endpoints,
- API key, delegated bearer token, and OAuth2 client credentials authentication helpers,
- optional LangChain and LangGraph integration helpers.

## Quick start

```python
import uuid

from api_mapper_client import ApiMapperClient, ApiMapperClientOptions
from api_mapper_client.auth.api_key import ApiKeyCredentialProvider

client = ApiMapperClient(
    ApiMapperClientOptions(
        base_url="https://runtime.example.com",
        tenant_id=uuid.UUID("11111111-1111-1111-1111-111111111111"),
        client_id="my-ai-client",
        credentials=ApiKeyCredentialProvider("replace-with-your-api-key"),
    )
)

tools = await client.get_tools()
print([tool.name for tool in tools])
```

## Streaming (Streamable HTTP / SSE)

The Runtime's `/mcp` endpoint may answer a request either with a plain JSON body or, when it
prefers SSE responses, with an SSE-framed body (`Content-Type: text/event-stream`). The client
handles both transparently — no configuration is needed, and neither mode is a "fallback" of the
other. If an SSE response ever ends without producing a message frame, the client makes one
resumption attempt (`GET /mcp` with `Last-Event-ID`) before raising.

Two additional APIs come with this support:

**`close_session()`** — explicitly tears down the MCP session on the Runtime (`DELETE /mcp`).
Best-effort: a 404 (session already gone) is not treated as an error. It's called automatically by
`close()` / `__aexit__`, so you typically don't need to call it directly:

```python
async with client:
    tools = await client.get_tools()
# session is closed automatically on exit

# or explicitly, without closing the underlying HTTP client:
await client.close_session()
```

**`listen()`** — opens the Runtime's standalone server-push stream (`GET /mcp`) and yields each
message as a dict. It reconnects automatically on transient faults (using `Last-Event-ID` so the
Runtime can resume/replay), and stops immediately if the session is unknown/expired or a stream is
already open:

```python
async for message in client.listen():
    print(message)
```

## Correlation IDs

Send your application's own trace ID with each call and the Runtime records it against the execution
ID it generates, so you can retrieve the full platform audit trail for work you triggered. Configure
an ambient provider on the client options, or pass one per call. See the
[SDK correlation guide](https://github.com/CodedProjects/ApiMapper/blob/main/docs/SDK.md#correlation-ids).

## License

MIT
