Skip to main content

ivcap-lambda: Python SDK for Lambda-Style IVCAP Services

Package renamed: ivcap-ai-tool has been renamed to ivcap-lambda to 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 a DeprecationWarning prompting migration.

Coverity Scan Build Status

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 mcp Python SDK)

📖 Full documentation: https://ivcap-works.github.io/ivcap-ai-tool-sdk-python/

🚀 New to the library? Depending on your goal:

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)

Source distribution for ivcap-lambda 0.8.10
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)

Table of built distributions (wheels) for ivcap-lambda 0.8.10
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page