Metadata-Version: 2.4
Name: cogspace
Version: 0.1.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) — add a persistent knowledge layer to any AI agent.

## Install

```bash
pip install cogspace
```

## Quickstart

```python
from cogspace import Cogspace

cog = Cogspace(api_key="cs-...")

# Get a space-scoped client
space = cog.space("my-agent")

# Search
results = space.search("retry logic with backoff")
for r in results.results:
    print(r.file_path, r.score)

# Write knowledge
space.write("expertise/retry.md", """
# Retry patterns
Always use exponential backoff with jitter.
""")

# Read the hot layer (always-injected context)
context = space.hot_layer()

# Memory
space.write_memory("Currently working on the payment service refactor.")
memory = space.read_memory()
```

## Async

```python
from cogspace import AsyncCogspace

async def main():
    cog = AsyncCogspace(api_key="cs-...")
    space = await cog.space("my-agent")
    results = await space.search("retry logic")
    await cog.aclose()
```

Or use as a context manager:

```python
async with AsyncCogspace(api_key="cs-...") as cog:
    space = await cog.space("my-agent")
    await space.write("expertise/notes.md", "...")
```

## API Reference

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

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

### `SpaceClient`

| Method | Description |
|---|---|
| `space.search(query, mode, top_k, layer)` | Hybrid / vector / keyword search |
| `space.read(path)` | Read a file by path |
| `space.write(path, content, metadata)` | Write or update a file |
| `space.list(folder)` | List files in a folder |
| `space.read_memory()` | Read `memory.md` |
| `space.write_memory(content, confidence)` | Update `memory.md` |
| `space.read_context()` | Read `memory/user/` context files |
| `space.hot_layer()` | Get full hot layer injection string |
| `space.graph_traverse(path, depth, rel_type)` | Traverse knowledge graph |
| `space.health()` | Space health and storage stats |

## Errors

All exceptions inherit from `CogspaceError`:

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

try:
    space.search("query")
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), go to **Settings → API keys**, and create a key.
