Metadata-Version: 2.5
Name: axisdream
Version: 1.0.2
Summary: Official Axisdream SDK for the Context OS behind your work with AI
Project-URL: Homepage, https://axisdream.xyz
Project-URL: Documentation, https://axisdream.xyz/docs
Project-URL: Repository, https://github.com/Jack-Pision/axisdream
Project-URL: Issues, https://github.com/Jack-Pision/axisdream/issues
Author-email: Axisdream <sdk@axisdream.xyz>
License: MIT
Keywords: agents,ai,knowledge,memory,rag,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# axisdream

Official Python SDK for [Axisdream](https://axisdream.xyz) — thin client for the Axisdream Context OS.

Published on PyPI as **`axisdream`**.

## Install

```bash
pip install axisdream
```

## Quickstart

```python
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

```python
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.

| Method | Description |
|---|---|
| `cog.space(name_or_id)` | Get a space client by name or ID |
| `cog.list_spaces()` | List all your spaces |

### `SpaceClient`

| Method | Args | Description |
|---|---|---|
| `space.list(folder)` | `folder=""` | List files in folder |
| `space.fetch(path)` | `path` | Get one file with content + metadata |
| `space.retrieve(query, ...)` | see below | Ranked context discovery across semantic, lexical, and relationship signals |
| `space.add(path, content, bucket, topic, confidence, file_type, status, related, relates_to)` | see below | Create or replace one context file |
| `space.forget(path)` | `path` | Delete one file from the space |
| `space.get_tools()` | — | Fetch the Platform's live MCP-compatible tool schemas |

#### `add()` parameters

| Param | Type | Required | Description |
|---|---|---|---|
| `path` | str | yes | File path (e.g. "knowledge/retry.md") |
| `content` | str | yes | Markdown content |
| `bucket` | str | yes | "knowledge", "memory", "skills", or "state" |
| `topic` | str | yes | Category/topic |
| `confidence` | float | no | 0.0-1.0, default 0.9 |
| `file_type` | str | no | Explicit file type override |
| `status` | str | no | Metadata status, default `active` |
| `related` | list[str] | no | Canonical related file paths |
| `relates_to` | list[str] | no | Backward-compatible alias for `related` |

## Buckets

| Bucket | Use for |
|---|---|
| `knowledge` | Knowledge the space may need again |
| `memory` | What the work should carry forward |
| `skills` | Reusable ways of doing work |
| `state` | Current mission and compact working state such as `state/mission.md` and `state/memory.md` |

## 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:

| Param | Type | Default | Range | Description |
|---|---|---|---|---|
| `top_k` | int | 10 | 1–20 | Final accepted context chunks. Retrieval layers are coordinated automatically. |
| `bucket` | str | None | "knowledge"/"memory"/"skills"/"state" | Filter by bucket. |
| `folder_path` | str | None | — | Restrict to folder. |
| `query_variants` | list | required | Exactly 3 | One agent-generated `{query, kind}` probe for each of `rewrite`, `exact`, and `hyde`; the top-level query is raw. |

**Examples:**
```python
# 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

```python
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
