Metadata-Version: 2.4
Name: cogspace
Version: 0.3.0
Summary: Official Cogspace SDK — add a knowledge layer to any AI agent
Project-URL: Homepage, https://cogspace.ai
Project-URL: Documentation, https://docs.cogspace.ai
Project-URL: Repository, https://github.com/Jack-Pision/cogspace-ai
Project-URL: Issues, https://github.com/Jack-Pision/cogspace-ai/issues
Author-email: Cogspace <sdk@cogspace.ai>
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

# cogspace

Official Python SDK for [Cogspace](https://cogspace.ai) — persistent knowledge layer for AI agents.

## Install

```bash
pip install cogspace
```

## Quickstart

```python
import asyncio
import os
from cogspace import AsyncCogspace

# Set your API key (or pass api_key= directly)
os.environ["COGSPACE_API_KEY"] = "cs-..."

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

    # See what exists
    files = await space.list("expertise")
    print(f"Files: {files.file_count}")

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

    # Search
    results = await space.search("retry logic", limit=5)
    for item in results.results:
        print(f"{item.path}: {item.score:.2f}")

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

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

    await cog.aclose()

asyncio.run(main())
```

## Sync client

```python
from cogspace import Cogspace

with Cogspace() as cog:
    space = cog.space("my-agent")
    files = space.list("expertise")
    results = space.search("retry logic", limit=5)
    space.add(
        path="expertise/retry.md",
        content="# Retry Patterns\n...",
        layer="expertise",
        topic="retry-patterns",
    )
    space.forget("expertise/retry.md")
```

## API Reference

### `Cogspace(api_key, base_url, timeout, max_retries)`

Reads `COGSPACE_API_KEY` from environment if `api_key` not provided.

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

### `SpaceClient`

| Method | Args | Description |
|---|---|---|
| `space.list(folder)` | `folder=""` | List files in folder |
| `space.retrieve(path)` | `path` | Get one file with content + metadata |
| `space.search(query, limit, layer)` | `limit=10`, `layer=None` | Search all layers |
| `space.add(path, content, layer, topic, confidence, relates_to)` | see below | Add/update knowledge |
| `space.forget(path)` | `path` | Delete from all layers |

#### `add()` parameters

| Param | Type | Required | Description |
|---|---|---|---|
| `path` | str | yes | File path (e.g. "expertise/retry.md") |
| `content` | str | yes | Markdown content |
| `layer` | str | yes | "expertise", "memory", or "root" |
| `topic` | str | yes | Category/topic |
| `confidence` | float | no | 0.0-1.0, default 0.9 |
| `relates_to` | list[str] | no | Related file names |

## Layers

| Layer | Use for |
|---|---|
| `expertise` | Knowledge, patterns, guides, reference material |
| `memory` | Agent memory, user preferences, session notes |
| `root` | General knowledge that doesn't fit elsewhere |

## Limits

- `search(limit=...)` — max 100 results per call
- `forget()` — single file per call

## Errors

```python
from cogspace.exceptions import AuthError, NotFoundError, RateLimitError, LimitExceededError

try:
    results = await space.search("query", limit=200)
except LimitExceededError:
    print("Limit must be <= 100")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Space not found")
```

## Get an API key

Sign in at [platform.cogspace.ai](https://platform.cogspace.ai) → **Settings → API keys** → **Create key**.
