ivcap-lambda: Python SDK for Lambda-Style IVCAP Services
Package renamed:
ivcap-ai-toolhas been renamed toivcap-lambdato reflect that the library is useful for any lambda-style IVCAP service, not just AI agent tools. A compatibility shim is published under the old name — existing apps will continue to work but will see aDeprecationWarningprompting migration.
ivcap-lambda is a Python library that turns a plain Python function into a set of
IVCAP-compatible HTTP endpoints and/or a spec-compliant MCP (Model Context
Protocol) server, from the same tool code. It sits on top of
ivcap-service and
FastAPI, and handles:
- Registering tool functions as HTTP endpoints (with async "try-later" semantics)
- Job execution in threads, result caching, and graceful shutdown
- Event/progress reporting back to the IVCAP platform
- Automatic tool-description endpoints (for AI agents) and an optional MCP endpoint
(built on the official
mcpPython SDK)
📖 Full documentation: https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/
🚀 New to the library? Depending on your goal:
- Building a service for the IVCAP platform (MCP optional) → see Track A or the Quick Start guide
- Building an MCP server first, with IVCAP deployment as a bonus → see Track B or the MCP guide's MCP-first section
- Migrating an existing server built on the plain
mcpPython SDK → see Track C - A ready-to-clone starter project → ivcap-python-ai-tool-template
See AGENTS.md for the full router between the three tracks above.
Installation
pip install ivcap-lambda
# To also expose tools as an MCP server:
pip install ivcap-lambda[mcp]
Minimal Example
from pydantic import BaseModel, Field
from ivcap_service import Service, getLogger, with_schema
from ivcap_lambda import start_lambda_server, ivcap_lambda, ToolOptions, logging_init
logging_init()
logger = getLogger("my-service")
service = Service(
name="My IVCAP Service",
description="A minimal example service.",
contact={"name": "Alice", "email": "alice@example.com"},
license={"name": "MIT", "url": "https://opensource.org/licenses/MIT"},
)
@with_schema("urn:example:schema:echo.request.1")
class EchoRequest(BaseModel):
message: str = Field(..., description="The message to echo back.")
@with_schema("urn:example:schema:echo.1")
class EchoResult(BaseModel):
echo: str = Field(..., description="The echoed message.")
@ivcap_lambda("/", opts=ToolOptions(tags=["Echo"]))
def echo(req: EchoRequest) -> EchoResult:
"""Echo a message
Returns the message passed in the request unchanged.
"""
return EchoResult(echo=req.message)
if __name__ == "__main__":
start_lambda_server(service)
Run and test it:
python my_service.py --port 8090
curl -X POST http://localhost:8090/ -H "content-type: application/json" -d '{"message": "Hello, IVCAP!"}'
# Or, with the mcp extra installed, run the exact same tool as an MCP server instead:
python my_service.py --with-mcp-stdio
For everything else — defining tools, ToolOptions, JobContext, progress
reporting, artifacts, MCP, project layout, deployment, Docker — see the
full documentation
and AGENTS.md. This README intentionally stays limited to
installation/quick-start plus notes for anyone working on ivcap-lambda
itself (below), to avoid duplicating content that's already maintained in the
docs site.
Migration from ivcap-ai-tool
| Old (deprecated) | New |
|---|---|
pip install ivcap-ai-tool |
pip install ivcap-lambda |
from ivcap_ai_tool import ... |
from ivcap_lambda import ... |
@ivcap_ai_tool(...) |
@ivcap_lambda(...) |
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.
Contributing / Developing ivcap-lambda Itself
The sections below are for anyone extending, fixing, or releasing this library — not for consumers of the package. See also CONTRIBUTING.md, DESIGN.md (internal architecture), and CONDUCT.md.
Repository Layout
ivcap-ai-tool/
├── ivcap_lambda/ # the library itself
├── compat/ # ivcap-ai-tool deprecation shim (old package name)
├── docs/ # MkDocs documentation site (docs/docs) + build output (docs/site)
├── examples/ # runnable example services (test-tool, test-mcp)
├── tests/ # unit tests
├── AGENTS.md # user-facing reference for AI coding agents
├── DESIGN.md # internal architecture & design rationale
└── pyproject.toml
Setup, Tests & Checks
poetry install
make test # pytest --cov=ivcap_lambda
make check # test + ruff check + mypy
Running the Example Services
cd examples/test-tool && poetry install && make run # REST example
cd examples/test-mcp && poetry install && make run # MCP example (HTTP)
cd examples/test-mcp && make run-mcp-stdio # MCP example (stdio)
Building & Serving the Documentation Site
make docs-serve # live-reload at a random local port
make docs-build # build static site into docs/site
Releasing
Versioning/publishing is driven by semantic_release config in
pyproject.toml on main. make build / make publish wrap poetry build/poetry publish.
License
Licensed under the BSD-style license in LICENSE. See AUTHORS.md for contributors.
Metadata
Release files for ivcap-lambda 0.8.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ivcap_lambda-0.8.10.tar.gz | 25.1 kB | Without provenance | Details for ivcap_lambda-0.8.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ivcap_lambda-0.8.10-py3-none-any.whl | Python 3 | none | any | Details for ivcap_lambda-0.8.10-py3-none-any.whl |
Total release size: 55.7 kB
Release files / ivcap_lambda-0.8.10.tar.gz
| Download URL | ivcap_lambda-0.8.10.tar.gz |
|---|---|
| Size | 25.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
716f9723ef3db3378c78d4af03b4d5286ef2fc4fbd76634ea7be6c6884306a55
|
|
BLAKE2b-256 checksum How to use checksums |
d913541b8f4abf93ade367801467c5b6a71440147cc7a37dbdf442d62469b6d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.14.5 Darwin/24.6.0
|
Release files / ivcap_lambda-0.8.10-py3-none-any.whl
| Download URL | ivcap_lambda-0.8.10-py3-none-any.whl |
|---|---|
| Size | 30.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c7a301897869adde7339f9fee3f8cdc07359fbfa3f8debfb7297bb48f54922d2
|
|
BLAKE2b-256 checksum How to use checksums |
03fd1559cb2b1df463aee11313fd34b2a49273b7d06330047b9536fe0932039d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.14.5 Darwin/24.6.0
|
Security for ivcap-lambda 0.8.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.