axisdream

Official Python SDK for Axisdream — thin client for the Axisdream Context OS.

Published on PyPI as axisdream.

Install

pip install axisdream

Quickstart

import asyncio
import os
from axisdream import AsyncAxisdream

# Set these once in your environment, or pass them to AsyncAxisdream directly.
os.environ["AXISDREAM_API_KEY"] = "cs-YOUR_KEY"
os.environ["AXISDREAM_BASE_URL"] = "https://your-axisdream-api.example"

async def main():
    cog = AsyncAxisdream()
    space = await cog.space("my-agent")

    # Add context
    await space.add(
        path="knowledge/retry.md",
        content="# Retry Patterns\nUse exponential backoff with jitter.",
        bucket="knowledge",
        topic="retry-patterns",
        confidence=0.95,
    )

    # Search first for substantive context. Axisdream coordinates all retrieval layers.
    results = await space.retrieve(
        "retry logic",
        top_k=10,         # final accepted context chunks (maximum 20)
        query_variants=[
            {"query": "retry logic with backoff failures", "kind": "rewrite"},
            {"query": "a passage describing reliable retry behavior with backoff and jitter", "kind": "hyde"},
            {"query": "retry backoff jitter", "kind": "exact"},
        ],
    )
    for item in results.results:
        print(f"{item.file_path}: {item.score:.2f} ({item.source})")

    # Retrieve a file
    file = await space.fetch("knowledge/retry.md")
    print(file.content)

    # Inspect structure only when a path or folder is specifically needed.
    files = await space.list("knowledge")
    print(f"Files: {files.file_count}")

    # Delete
    await space.forget("knowledge/retry.md")

    await cog.aclose()

asyncio.run(main())

Sync client

from axisdream import Axisdream

with Axisdream() as cog:
    space = cog.space("my-agent")
    results = space.retrieve(
        "retry logic",
        top_k=10,
        query_variants=[
            {"query": "retry logic with backoff failures", "kind": "rewrite"},
            {"query": "a passage describing reliable retry behavior with backoff and jitter", "kind": "hyde"},
            {"query": "retry backoff jitter", "kind": "exact"},
        ],
    )
    space.add(
        path="knowledge/retry.md",
        content="# Retry Patterns\n...",
        bucket="knowledge",
        topic="retry-patterns",
    )
    space.forget("knowledge/retry.md")

API Reference

Axisdream(api_key, base_url, timeout, max_retries)

Reads AXISDREAM_API_KEY from environment if api_key is not provided. Reads AXISDREAM_BASE_URL if base_url is not provided, then falls back to http://localhost:8000 for local development.

SpaceClient

add() parameters

Buckets

Search limits

retrieve() parameters (enforced at backend). The backend automatically coordinates the available retrieval sources; these values adjust candidate coverage rather than selecting an engine:

Examples:

# Adjust coverage while keeping the backend retrieval pipeline automatic
results = await space.retrieve("query", top_k=10)

# Multi-aspect retrieval: one call, bounded and deduplicated by Axisdream
results = await space.retrieve(
    "design the onboarding modal",
    query_variants=[
        {"query": "modal composition and hierarchy", "kind": "rewrite"},
        {"query": "accessible onboarding dialog behavior", "kind": "exact"},
    ],
    top_k=10,
)

Errors

from axisdream.exceptions import AuthError, NotFoundError, RateLimitError

try:
    results = await space.retrieve("query")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Space not found")
except RateLimitError:
    print("Rate limited, retry later")

Local-first note

The Python SDK uses the configured hosted URL when available:

• Base URL precedence: base_url, then AXISDREAM_BASE_URL, then http://localhost:8000
• Space lookup accepts either a space name or a space ID