Umbrella SDK

aice-sdk (Python) and @aiceafrica/sdk (TypeScript) put every service client behind one Aice object. Each sub-client is built the first time you touch it, so importing the umbrella costs nothing for services you never call.

import os
from aice import Aice

aice = Aice(
    api_key=os.environ["AICE_API_KEY"],
    user_id=current_user.id,
    user_role=current_user.role,
    base_urls={
        "reco": "https://reco.example.com/ecommerce",
        "knowledge": "https://kb.example.com/knowledge",
        "crawler": "https://crawler.example.com/crawl",
        "agent-platform": "https://agents.example.com",
        "kyc": "https://kyc.example.com",
        "data-brain": "https://brain.example.com",
    },
)

recs = aice.reco.recommend("user-1", n=10)
hits = aice.knowledge.search("payment terms")
jobs = aice.crawler.jobs.list()

Each URL includes the service's path; see Service URLs. A service you leave out falls back to a bare local port without its path, so list every service you call.

Sub-clientsCopy Anchor Link

The Python base_urls keys are kebab-case ("agent-platform", "data-brain"); the TypeScript keys are camelCase.

Recommendation is reco on the umbrella even though its class is RecommendationClient. That short name is kept on purpose as the stable handle.

Serving many usersCopy Anchor Link

The umbrella passes its user to each sub-client. To act for someone else per request:

from aice_core import acting_as

with acting_as(request.user.id, role=request.user.role):
    recs = aice.reco.recommend("user-1", n=10)

withUser returns a new Aice that rebuilds its sub-clients lazily; the original is untouched.

What isn't includedCopy Anchor Link

• Sandbox identifies the tenant and user per session rather than per request, so it doesn't fit one-key-for-everything. Install aice-sandbox on its own.
• Observability isn't an API client. It's a telemetry bootstrap for your own services; see Observability.