Python SDK

The Python SDK is published as illumina-client and imported as illumina_client. Its Illumina class wraps every common operation, and every method ships with an a-prefixed async twin (retain/aretain, recall/arecall, and so on) that uses its own transport — neither variant depends on the other's event loop.

Install

pip install illumina-client

Requires Python 3.10 or newer.

Initialize

Construct the client with the hosted base URL and your API key. The key is sent as a bearer token on every request:

from illumina_client import Illumina
 
client = Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...")

The full constructor is Illumina(base_url, api_key=None, timeout=300.0, user_agent=None):

Async

Every method has an async counterpart prefixed with a. The client is also a context manager (sync and async) that closes its transports on exit:

import asyncio
from illumina_client import Illumina
 
async def main():
    async with Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...") as client:
        await client.aretain(namespace_id="alice", content="Alice loves AI")
        response = await client.arecall(namespace_id="alice", query="What does Alice like?")
        for result in response.results:
            print(result.text)
 
asyncio.run(main())

Core operations

Memories live in namespaces, and retain does not auto-create one — create it first:

client.create_namespace(namespace_id="alice")

Retain

Store raw text; Illumina extracts facts, entities, and relationships:

client.retain(
    namespace_id="alice",
    content="Ada shipped the payments rewrite in Q3 2025.",
    context="standup notes",
    tags=["work"],
)

retain also accepts timestamp, document_id, metadata, entities ([{"text": "...", "type": "..."}]), update_mode ("replace" or "append"), fact_type ("world", "experience", or "decision"), and retain_async=True to process in the background.

Use retain_batch for multiple memories in one request — each item is a dict with a required content key:

client.retain_batch(
    namespace_id="alice",
    items=[
        {"content": "Alice loves hiking"},
        {"content": "Alice visited Paris", "context": "travel", "timestamp": "2024-07-01"},
    ],
)

retain_files(namespace_id, files, context=None, files_metadata=None) uploads files, always processes them asynchronously, and returns operation IDs for tracking progress.

Recall

Query a namespace by semantic similarity. budget ("low", "mid", "high") controls retrieval effort and defaults to "mid"; max_tokens defaults to 4096:

response = client.recall(
    namespace_id="alice",
    query="What are Alice's hobbies?",
    budget="mid",
    include_entities=True,
)
for result in response.results:
    print(result.text, result.type_)

Other keyword arguments: types (filter by fact type), tags and tags_match ("any", "all", "any_strict", "all_strict"), tag_groups (compound boolean tag filters), include_chunks, include_source_facts, query_timestamp, and trace.

RecallResponse is iterable, supports len(), and has .to_prompt_string() to serialize results for LLM prompts. Each RecallResult carries .text, .type_, and optional .context and temporal fields.

Reflect

Ask a higher-level question over everything the namespace knows. budget defaults to "low"; the answer is on .text:

answer = client.reflect(
    namespace_id="alice",
    query="Summarize Ada's recent work",
    include_facts=True,
)
print(answer.text)

Other keyword arguments: context, max_tokens, response_schema (a JSON Schema — the response then includes structured_output), tags, tags_match, tag_groups, fact_types, exclude_automations, and exclude_automation_ids. include_facts=True adds a based_on field listing the sources used.

Error handling

Any non-success (>= 400) response raises IlluminaAPIError, which carries status_code, detail, and the raw content:

from illumina_client import Illumina, IlluminaAPIError
 
client = Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...")
 
try:
    client.recall(namespace_id="missing", query="anything")
except IlluminaAPIError as err:
    print(err.status_code, err.detail)

Method reference

Every method below exists in sync and async (a-prefixed) form.

Retain

Recall

Reflect

Memories

Namespaces

Namespace config

Namespace templates

Automations

create_automation and update_automation accept a trigger_refresh_after_consolidation: bool shortcut that expands to trigger={"refresh_after_consolidation": value}; an explicit trigger dict takes precedence.

Directives

Documents

Entities

Ontology

Communities

Audit

Beyond the wrapper

For operations without a convenience method (async operations, webhooks, monitoring, remaining entity ops), use the per-group accessors, which pre-bind the low-level client:

client.documents.delete_document.sync(namespace_id, document_id)
await client.operations.get_operation_status.asyncio(namespace_id, op_id)

Available groups: memory, namespaces, documents, entities, automations, directives, operations, webhooks, files, monitoring, audit, communities, ontology, and namespace_templates. Each operation exposes sync, sync_detailed, asyncio, and asyncio_detailed.