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.7

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.7
File Size Uploaded Provenance Actions
ivcap_lambda-0.8.7.tar.gz 24.7 kB Without provenance Details for ivcap_lambda-0.8.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ivcap-lambda 0.8.7
File Interpreter ABI Platform Actions
ivcap_lambda-0.8.7-py3-none-any.whl Python 3 none any Details for ivcap_lambda-0.8.7-py3-none-any.whl

Total release size: 54.7 kB

Release files / ivcap_lambda-0.8.7.tar.gz

Download URL ivcap_lambda-0.8.7.tar.gz
Size 24.7 kB
Tags Source
SHA-256 checksum
How to use checksums
03cffdd1ff04033659a6d750bc2233d7dd61a6703f223910605401e608e8f614
BLAKE2b-256 checksum
How to use checksums
baf6d7bafd1170e3e5f1f58b6d663ba4a6766d43e2b3e19b4174d5eb6d0b9056
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.7-py3-none-any.whl

Download URL ivcap_lambda-0.8.7-py3-none-any.whl
Size 30.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6baa26845ce21d7c9ea60ba03304a19ce4436f8c021a160791a964712d422437
BLAKE2b-256 checksum
How to use checksums
f1f618389117fd92f2705da4f89377486df9e7b23531808ebdbf8992bd984eb1
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.7

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