ivcap-lambda 0.7.25__tar.gz → 0.8.2__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.
@@ -0,0 +1,204 @@
1
+ Metadata-Version: 2.4
2
+ Name: ivcap-lambda
3
+ Version: 0.8.2
4
+ Summary: Helper functions for building lambda-style services on the IVCAP platform
5
+ License-File: AUTHORS.md
6
+ License-File: LICENSE
7
+ Author: Max Ott
8
+ Author-email: max.ott@csiro.au
9
+ Requires-Python: >=3.11,<4.0
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Provides-Extra: mcp
16
+ Requires-Dist: cachetools (>=5.5.2,<6.0.0)
17
+ Requires-Dist: fastapi (>=0.121.2,<0.122.0)
18
+ Requires-Dist: ivcap-service (>=0.7.0,<0.8.0)
19
+ Requires-Dist: mcp (>=2.3.0,<3.0.0) ; extra == "mcp"
20
+ Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0)
21
+ Requires-Dist: uuid6 (==2024.7.10)
22
+ Requires-Dist: uvicorn (>=0.38.0,<0.39.0)
23
+ Description-Content-Type: text/markdown
24
+
25
+ # ivcap-lambda: Python SDK for Lambda-Style IVCAP Services
26
+
27
+ > **Package renamed:** `ivcap-ai-tool` has been renamed to `ivcap-lambda` to reflect that
28
+ > the library is useful for any lambda-style IVCAP service, not just AI agent tools.
29
+ > A [compatibility shim](./compat/) is published under the old name — existing apps
30
+ > will continue to work but will see a `DeprecationWarning` prompting migration.
31
+
32
+ <a href="https://scan.coverity.com/projects/ivcap-works-ivcap-ai-tool-sdk-python">
33
+ <img alt="Coverity Scan Build Status"
34
+ src="https://img.shields.io/coverity/scan/31491.svg"/>
35
+ </a>
36
+
37
+ `ivcap-lambda` is a Python library that turns a plain Python function into a set of
38
+ **IVCAP-compatible HTTP endpoints** and/or a **spec-compliant MCP (Model Context
39
+ Protocol) server**, from the same tool code. It sits on top of
40
+ [`ivcap-service`](https://pypi.org/project/ivcap-service/) and
41
+ [FastAPI](https://fastapi.tiangolo.com/), and handles:
42
+
43
+ - Registering tool functions as HTTP endpoints (with async "try-later" semantics)
44
+ - Job execution in threads, result caching, and graceful shutdown
45
+ - Event/progress reporting back to the IVCAP platform
46
+ - Automatic tool-description endpoints (for AI agents) and an optional MCP endpoint
47
+ (built on the official [`mcp`](https://pypi.org/project/mcp/) Python SDK)
48
+
49
+ **📖 Full documentation:** <https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/>
50
+
51
+ **🚀 New to the library?** Depending on your goal:
52
+
53
+ - Building a service for the **IVCAP platform** (MCP optional) → see
54
+ [Track A](./docs/agents/track-a-ivcap-service.md) or the
55
+ [Quick Start guide](https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/getting-started/quick-start/)
56
+ - Building an **MCP server** first, with IVCAP deployment as a bonus → see
57
+ [Track B](./docs/agents/track-b-mcp-first.md) or the
58
+ [MCP guide's MCP-first section](https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/guides/mcp/#mcp-first-development)
59
+ - Migrating an existing server built on the plain **`mcp` Python SDK** → see
60
+ [Track C](./docs/agents/track-c-migrate-from-mcp.md)
61
+ - A ready-to-clone starter project →
62
+ [ivcap-python-ai-tool-template](https://github.com/ivcap-works/ivcap-python-ai-tool-template)
63
+
64
+ See [AGENTS.md](./AGENTS.md) for the full router between the three tracks above.
65
+
66
+ ---
67
+
68
+ ## Installation
69
+
70
+ ```bash
71
+ pip install ivcap-lambda
72
+
73
+ # To also expose tools as an MCP server:
74
+ pip install ivcap-lambda[mcp]
75
+ ```
76
+
77
+ ## Minimal Example
78
+
79
+ ```python
80
+ from pydantic import BaseModel, Field
81
+ from ivcap_service import Service, getLogger, with_schema
82
+ from ivcap_lambda import start_lambda_server, ivcap_lambda, ToolOptions, logging_init
83
+
84
+ logging_init()
85
+ logger = getLogger("my-service")
86
+
87
+ service = Service(
88
+ name="My IVCAP Service",
89
+ description="A minimal example service.",
90
+ contact={"name": "Alice", "email": "alice@example.com"},
91
+ license={"name": "MIT", "url": "https://opensource.org/licenses/MIT"},
92
+ )
93
+
94
+
95
+ @with_schema("urn:example:schema:echo.request.1")
96
+ class EchoRequest(BaseModel):
97
+ message: str = Field(..., description="The message to echo back.")
98
+
99
+
100
+ @with_schema("urn:example:schema:echo.1")
101
+ class EchoResult(BaseModel):
102
+ echo: str = Field(..., description="The echoed message.")
103
+
104
+
105
+ @ivcap_lambda("/", opts=ToolOptions(tags=["Echo"]))
106
+ def echo(req: EchoRequest) -> EchoResult:
107
+ """Echo a message
108
+
109
+ Returns the message passed in the request unchanged.
110
+ """
111
+ return EchoResult(echo=req.message)
112
+
113
+
114
+ if __name__ == "__main__":
115
+ start_lambda_server(service)
116
+ ```
117
+
118
+ Run and test it:
119
+
120
+ ```bash
121
+ python my_service.py --port 8090
122
+ curl -X POST http://localhost:8090/ -H "content-type: application/json" -d '{"message": "Hello, IVCAP!"}'
123
+
124
+ # Or, with the mcp extra installed, run the exact same tool as an MCP server instead:
125
+ python my_service.py --with-mcp-stdio
126
+ ```
127
+
128
+ For everything else — defining tools, `ToolOptions`, `JobContext`, progress
129
+ reporting, artifacts, MCP, project layout, deployment, Docker — see the
130
+ **[full documentation](https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/)**
131
+ and **[AGENTS.md](./AGENTS.md)**. This README intentionally stays limited to
132
+ installation/quick-start plus notes for anyone working on `ivcap-lambda`
133
+ itself (below), to avoid duplicating content that's already maintained in the
134
+ docs site.
135
+
136
+ ---
137
+
138
+ ## Migration from `ivcap-ai-tool`
139
+
140
+ | Old (deprecated) | New |
141
+ |---|---|
142
+ | `pip install ivcap-ai-tool` | `pip install ivcap-lambda` |
143
+ | `from ivcap_ai_tool import ...` | `from ivcap_lambda import ...` |
144
+ | `@ivcap_ai_tool(...)` | `@ivcap_lambda(...)` |
145
+
146
+ The old `ivcap-ai-tool` package is a compatibility shim that re-exports everything from `ivcap-lambda`. It will emit a `DeprecationWarning` at import time. No code changes beyond the import are required.
147
+
148
+ ---
149
+
150
+ ## Contributing / Developing `ivcap-lambda` Itself
151
+
152
+ The sections below are for anyone extending, fixing, or releasing this
153
+ library — not for consumers of the package. See also
154
+ [CONTRIBUTING.md](./CONTRIBUTING.md), [DESIGN.md](./DESIGN.md) (internal
155
+ architecture), and [CONDUCT.md](./CONDUCT.md).
156
+
157
+ ### Repository Layout
158
+
159
+ ```
160
+ ivcap-ai-tool/
161
+ ├── ivcap_lambda/ # the library itself
162
+ ├── compat/ # ivcap-ai-tool deprecation shim (old package name)
163
+ ├── docs/ # MkDocs documentation site (docs/docs) + build output (docs/site)
164
+ ├── examples/ # runnable example services (test-tool, test-mcp)
165
+ ├── tests/ # unit tests
166
+ ├── AGENTS.md # user-facing reference for AI coding agents
167
+ ├── DESIGN.md # internal architecture & design rationale
168
+ └── pyproject.toml
169
+ ```
170
+
171
+ ### Setup, Tests & Checks
172
+
173
+ ```bash
174
+ poetry install
175
+ make test # pytest --cov=ivcap_lambda
176
+ make check # test + ruff check + mypy
177
+ ```
178
+
179
+ ### Running the Example Services
180
+
181
+ ```bash
182
+ cd examples/test-tool && poetry install && make run # REST example
183
+ cd examples/test-mcp && poetry install && make run # MCP example (HTTP)
184
+ cd examples/test-mcp && make run-mcp-stdio # MCP example (stdio)
185
+ ```
186
+
187
+ ### Building & Serving the Documentation Site
188
+
189
+ ```bash
190
+ make docs-serve # live-reload at a random local port
191
+ make docs-build # build static site into docs/site
192
+ ```
193
+
194
+ ### Releasing
195
+
196
+ Versioning/publishing is driven by `semantic_release` config in
197
+ `pyproject.toml` on `main`. `make build` / `make publish` wrap `poetry
198
+ build`/`poetry publish`.
199
+
200
+ ### License
201
+
202
+ Licensed under the BSD-style license in [LICENSE](./LICENSE). See
203
+ [AUTHORS.md](./AUTHORS.md) for contributors.
204
+
@@ -0,0 +1,179 @@
1
+ # ivcap-lambda: Python SDK for Lambda-Style IVCAP Services
2
+
3
+ > **Package renamed:** `ivcap-ai-tool` has been renamed to `ivcap-lambda` to reflect that
4
+ > the library is useful for any lambda-style IVCAP service, not just AI agent tools.
5
+ > A [compatibility shim](./compat/) is published under the old name — existing apps
6
+ > will continue to work but will see a `DeprecationWarning` prompting migration.
7
+
8
+ <a href="https://scan.coverity.com/projects/ivcap-works-ivcap-ai-tool-sdk-python">
9
+ <img alt="Coverity Scan Build Status"
10
+ src="https://img.shields.io/coverity/scan/31491.svg"/>
11
+ </a>
12
+
13
+ `ivcap-lambda` is a Python library that turns a plain Python function into a set of
14
+ **IVCAP-compatible HTTP endpoints** and/or a **spec-compliant MCP (Model Context
15
+ Protocol) server**, from the same tool code. It sits on top of
16
+ [`ivcap-service`](https://pypi.org/project/ivcap-service/) and
17
+ [FastAPI](https://fastapi.tiangolo.com/), and handles:
18
+
19
+ - Registering tool functions as HTTP endpoints (with async "try-later" semantics)
20
+ - Job execution in threads, result caching, and graceful shutdown
21
+ - Event/progress reporting back to the IVCAP platform
22
+ - Automatic tool-description endpoints (for AI agents) and an optional MCP endpoint
23
+ (built on the official [`mcp`](https://pypi.org/project/mcp/) Python SDK)
24
+
25
+ **📖 Full documentation:** <https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/>
26
+
27
+ **🚀 New to the library?** Depending on your goal:
28
+
29
+ - Building a service for the **IVCAP platform** (MCP optional) → see
30
+ [Track A](./docs/agents/track-a-ivcap-service.md) or the
31
+ [Quick Start guide](https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/getting-started/quick-start/)
32
+ - Building an **MCP server** first, with IVCAP deployment as a bonus → see
33
+ [Track B](./docs/agents/track-b-mcp-first.md) or the
34
+ [MCP guide's MCP-first section](https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/guides/mcp/#mcp-first-development)
35
+ - Migrating an existing server built on the plain **`mcp` Python SDK** → see
36
+ [Track C](./docs/agents/track-c-migrate-from-mcp.md)
37
+ - A ready-to-clone starter project →
38
+ [ivcap-python-ai-tool-template](https://github.com/ivcap-works/ivcap-python-ai-tool-template)
39
+
40
+ See [AGENTS.md](./AGENTS.md) for the full router between the three tracks above.
41
+
42
+ ---
43
+
44
+ ## Installation
45
+
46
+ ```bash
47
+ pip install ivcap-lambda
48
+
49
+ # To also expose tools as an MCP server:
50
+ pip install ivcap-lambda[mcp]
51
+ ```
52
+
53
+ ## Minimal Example
54
+
55
+ ```python
56
+ from pydantic import BaseModel, Field
57
+ from ivcap_service import Service, getLogger, with_schema
58
+ from ivcap_lambda import start_lambda_server, ivcap_lambda, ToolOptions, logging_init
59
+
60
+ logging_init()
61
+ logger = getLogger("my-service")
62
+
63
+ service = Service(
64
+ name="My IVCAP Service",
65
+ description="A minimal example service.",
66
+ contact={"name": "Alice", "email": "alice@example.com"},
67
+ license={"name": "MIT", "url": "https://opensource.org/licenses/MIT"},
68
+ )
69
+
70
+
71
+ @with_schema("urn:example:schema:echo.request.1")
72
+ class EchoRequest(BaseModel):
73
+ message: str = Field(..., description="The message to echo back.")
74
+
75
+
76
+ @with_schema("urn:example:schema:echo.1")
77
+ class EchoResult(BaseModel):
78
+ echo: str = Field(..., description="The echoed message.")
79
+
80
+
81
+ @ivcap_lambda("/", opts=ToolOptions(tags=["Echo"]))
82
+ def echo(req: EchoRequest) -> EchoResult:
83
+ """Echo a message
84
+
85
+ Returns the message passed in the request unchanged.
86
+ """
87
+ return EchoResult(echo=req.message)
88
+
89
+
90
+ if __name__ == "__main__":
91
+ start_lambda_server(service)
92
+ ```
93
+
94
+ Run and test it:
95
+
96
+ ```bash
97
+ python my_service.py --port 8090
98
+ curl -X POST http://localhost:8090/ -H "content-type: application/json" -d '{"message": "Hello, IVCAP!"}'
99
+
100
+ # Or, with the mcp extra installed, run the exact same tool as an MCP server instead:
101
+ python my_service.py --with-mcp-stdio
102
+ ```
103
+
104
+ For everything else — defining tools, `ToolOptions`, `JobContext`, progress
105
+ reporting, artifacts, MCP, project layout, deployment, Docker — see the
106
+ **[full documentation](https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/)**
107
+ and **[AGENTS.md](./AGENTS.md)**. This README intentionally stays limited to
108
+ installation/quick-start plus notes for anyone working on `ivcap-lambda`
109
+ itself (below), to avoid duplicating content that's already maintained in the
110
+ docs site.
111
+
112
+ ---
113
+
114
+ ## Migration from `ivcap-ai-tool`
115
+
116
+ | Old (deprecated) | New |
117
+ |---|---|
118
+ | `pip install ivcap-ai-tool` | `pip install ivcap-lambda` |
119
+ | `from ivcap_ai_tool import ...` | `from ivcap_lambda import ...` |
120
+ | `@ivcap_ai_tool(...)` | `@ivcap_lambda(...)` |
121
+
122
+ The old `ivcap-ai-tool` package is a compatibility shim that re-exports everything from `ivcap-lambda`. It will emit a `DeprecationWarning` at import time. No code changes beyond the import are required.
123
+
124
+ ---
125
+
126
+ ## Contributing / Developing `ivcap-lambda` Itself
127
+
128
+ The sections below are for anyone extending, fixing, or releasing this
129
+ library — not for consumers of the package. See also
130
+ [CONTRIBUTING.md](./CONTRIBUTING.md), [DESIGN.md](./DESIGN.md) (internal
131
+ architecture), and [CONDUCT.md](./CONDUCT.md).
132
+
133
+ ### Repository Layout
134
+
135
+ ```
136
+ ivcap-ai-tool/
137
+ ├── ivcap_lambda/ # the library itself
138
+ ├── compat/ # ivcap-ai-tool deprecation shim (old package name)
139
+ ├── docs/ # MkDocs documentation site (docs/docs) + build output (docs/site)
140
+ ├── examples/ # runnable example services (test-tool, test-mcp)
141
+ ├── tests/ # unit tests
142
+ ├── AGENTS.md # user-facing reference for AI coding agents
143
+ ├── DESIGN.md # internal architecture & design rationale
144
+ └── pyproject.toml
145
+ ```
146
+
147
+ ### Setup, Tests & Checks
148
+
149
+ ```bash
150
+ poetry install
151
+ make test # pytest --cov=ivcap_lambda
152
+ make check # test + ruff check + mypy
153
+ ```
154
+
155
+ ### Running the Example Services
156
+
157
+ ```bash
158
+ cd examples/test-tool && poetry install && make run # REST example
159
+ cd examples/test-mcp && poetry install && make run # MCP example (HTTP)
160
+ cd examples/test-mcp && make run-mcp-stdio # MCP example (stdio)
161
+ ```
162
+
163
+ ### Building & Serving the Documentation Site
164
+
165
+ ```bash
166
+ make docs-serve # live-reload at a random local port
167
+ make docs-build # build static site into docs/site
168
+ ```
169
+
170
+ ### Releasing
171
+
172
+ Versioning/publishing is driven by `semantic_release` config in
173
+ `pyproject.toml` on `main`. `make build` / `make publish` wrap `poetry
174
+ build`/`poetry publish`.
175
+
176
+ ### License
177
+
178
+ Licensed under the BSD-style license in [LICENSE](./LICENSE). See
179
+ [AUTHORS.md](./AUTHORS.md) for contributors.
@@ -155,7 +155,12 @@ class Executor(Generic[T]):
155
155
  raise Exception(f"unexpected function parameter '{k}'")
156
156
 
157
157
  async def execute(
158
- self, param: Any, job_id: str, req: Request, report_result=True
158
+ self,
159
+ param: Any,
160
+ job_id: str,
161
+ req: Request,
162
+ report_result: bool = True,
163
+ reporter: EventReporter | None = None,
159
164
  ) -> asyncio.Queue[T | ExecutionError]:
160
165
  """
161
166
  Execute the function with the given parameter in a thread and return a queue with the result.
@@ -163,7 +168,13 @@ class Executor(Generic[T]):
163
168
  Args:
164
169
  param: Any The parameter to pass to the function
165
170
  job_id: str ID of this job
166
- req: Request FastAPI's request object
171
+ req: Request FastAPI's request object (or any duck-typed object
172
+ exposing a `.headers.get(...)` mapping, e.g. an MCP request shim)
173
+ report_result: whether to push the result back to the IVCAP sidecar
174
+ reporter: optional `EventReporter` instance to use for this invocation
175
+ instead of the one produced by the globally configured event-reporter
176
+ factory (e.g. `SidecarReporter`). Used to bridge progress reporting to
177
+ non-REST transports such as MCP.
167
178
 
168
179
  Returns:
169
180
  An asyncio Queue that will contain either the result of type T or an ExecutionError
@@ -200,7 +211,9 @@ class Executor(Generic[T]):
200
211
  jctxt = JobContext(
201
212
  job_id=job_id,
202
213
  job_authorization=authorization,
203
- report=create_event_reporter(
214
+ report=reporter
215
+ if reporter is not None
216
+ else create_event_reporter(
204
217
  job_id=job_id, job_authorization=authorization
205
218
  ),
206
219
  )