IntentLayerDocs
⌘K
Dashboard ↗
Docs/SDKs
SDKs

Python SDK reference

Every public Python SDK symbol, parameter, return type, and behavior from source.

Public package exports exactly six symbols: init, gate, gate_async, record_outcome, wrap, and GateResult.

#init

python
intentlayer.init(
    api_key: str = "",
    base_url: str = "http://localhost:8000",
    mode: Literal["suggest", "auto", "observe"] = "suggest",
) -> None

Updates process-global SDK config. Trailing slash is removed from base URL. Invalid mode raises ValueError. Timeout is internal fixed default 8.0 seconds; public init has no timeout parameter.

#gate

python
intentlayer.gate(
    request: str,
    session_id: str,
    context: dict[str, Any] | None = None,
    clarification_response: str | None = None,
) -> GateResult

Synchronously posts POST /v1/gate. clarification_response lets backend answer latest open clarification in session. Network, HTTP, parsing, and unexpected errors return clear fallback rather than raising.

#gate_async

python
await intentlayer.gate_async(
    request: str,
    session_id: str,
    context: dict[str, Any] | None = None,
    clarification_response: str | None = None,
) -> GateResult

Same request and fallback contract as gate, using httpx.AsyncClient.

#GateResult

python
@dataclass
class GateResult:
    ambiguity_score: float
    dimensions: dict[str, float]
    questions: list[str]
    intent_spec: dict[str, Any] | None

Fields use backend snake_case.

#record_outcome

python
intentlayer.record_outcome(
    session_id: str,
    event: Literal["rephrase", "accept", "regenerate", "abandon", "correction"],
    detail: str = "",
    *,
    gate_caught: bool = False,
) -> None

Starts daemon thread that posts POST /v1/events. Returns immediately. Delivery errors are debug-logged and dropped.

#wrap

python
intentlayer.wrap(func: Callable) -> Callable

Decorator expects first two call arguments to be request and session_id. Sync function calls gate; coroutine calls gate_async; then original function runs with unchanged args. Gate result is not passed to function and does not block it.

python
@intentlayer.wrap
async def agent(request: str, session_id: str) -> str:
    return await run(request)
Source truthsdk/intentlayer/__init__.pysdk/intentlayer/client.py