alavida-sdk

Python SDK for building Alavida platform components.

Install

pip install alavida-sdk

# With FastAPI helpers:
pip install "alavida-sdk[fastapi]"

Quick Start (FastAPI)

from fastapi import FastAPI, Depends
from alavida_sdk import (
    ComponentSchema, ActionSchema, define_schema,
    complete_job, fail_job, update_progress,
)
from alavida_sdk.fastapi import AlavidaMiddleware, require_auth
from alavida_sdk.types import AuthContext

app = FastAPI()
app.add_middleware(AlavidaMiddleware)  # rejects direct access, allows /health + /schema

# 1. Declare your schema
SCHEMA = ComponentSchema(
    slug="buying-signals",
    name="Buying Signals",
    type="workflow",
    version="1.0.0",
    actions={
        "run": ActionSchema(
            description="Detect buying signals for a list of companies",
            input_schema={
                "type": "object",
                "required": ["companies"],
                "properties": {
                    "companies": {"type": "array", "items": {"type": "object"}},
                },
            },
            output_schema={
                "type": "object",
                "properties": {
                    "companies": {"type": "array"},
                    "summary": {"type": "object"},
                },
            },
        ),
    },
)

@app.get("/health")
async def health():
    return {"status": "ok", "version": "1.0.0"}

@app.get("/schema")
async def schema():
    return define_schema(SCHEMA)

# 2. Handle execution — read auth context from gateway headers
@app.post("/run")
async def run(ctx: AuthContext = Depends(require_auth)):
    input_data = ...  # parse request body

    # Start background processing, return 202
    # When done, call complete_job()
    return {"status": "accepted"}

# 3. After background work finishes:
async def on_complete(callback_url: str, result: dict, credits: int):
    await complete_job(callback_url, result=result, credits_used=credits)

async def on_failure(callback_url: str, error: Exception):
    await fail_job(callback_url, error_code="processing_failed", error_message=str(error))

API Reference

Core (framework-agnostic)

FastAPI Helpers (alavida_sdk.fastapi)

Types

Exceptions

Environment Variables