Metadata-Version: 2.4
Name: khive
Version: 1.0.0rc1
Summary: Python client for the khive cognitive infrastructure API
Project-URL: Homepage, https://khive.ai
Project-URL: Documentation, https://docs.khive.dev/python
Project-URL: Repository, https://github.com/khive-ai/khive-python
Author-email: Ocean Li <quantocean.li@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# khive

Python client for the khive cognitive infrastructure API.

> **Preview release** — 4 services: memory, communication, work, graph.

- **Sync and async** — both `Khive` and `AsyncKhive` clients
- **Fully typed** — Pydantic response models, complete type annotations
- **Agent integration** — tool schemas for OpenAI, Anthropic, and MCP
- **Retry with backoff** — exponential backoff with jitter, respects `Retry-After`

## Installation

```bash
pip install khive
```

## Quick Start

```python
from khive import Khive

client = Khive(api_key="your-api-key")

# Store a memory
client.memory.remember(content="Quarterly review on March 15th")

# Recall memories by semantic search
results = client.memory.recall(query="quarterly review")

# Create a task
client.work.assign(title="Prepare slides", priority="p1")

# Send a message
client.communication.send(content="Slides ready", to="team")

# Knowledge graph
client.graph.create(type="person", name="Alice", role="engineer")
client.graph.link(source="node_1", target="node_2", relation="works_with")
```

## Authentication

```bash
export KHIVE_API_KEY="your-api-key"
```

Or pass directly:

```python
client = Khive(api_key="your-api-key")
```

## Services

### Memory (11 operations)

```python
client.memory.recall(query="meeting notes", limit=5)
client.memory.remember(content="Sprint planning Monday 10am", tags=["recurring"])
client.memory.update(id="mem_123", importance=0.9)
client.memory.forget(id="mem_123")
client.memory.list(memory_type="episodic")
client.memory.feedback(memory_ids=["mem_123"], signal="positive")
client.memory.stats()

# Observational notes
from khive.types import NoteTarget
client.memory.note_create(
    targets=[NoteTarget(kind="memory", id="mem_123")],
    content="Frequently recalled in planning contexts",
)
```

### Communication (18 operations)

```python
client.communication.send(content="Status update", to="lambda:leo")
client.communication.list(status="unread")
client.communication.search(query="deployment")
client.communication.mark_read(message_id="msg_123")
client.communication.thread(thread_id="thread_123")
client.communication.discuss(discuss_action="start", topic="Architecture review")
client.communication.overview()
```

### Work (25 operations)

```python
client.work.next(limit=5)
client.work.assign(title="Fix login bug", priority="p1", energy="high")
client.work.complete(id="task_123")
client.work.schedule_add(title="Team standup", start="2026-05-01T10:00:00")
client.work.schedule_today()
client.work.areas()
client.work.project_create(area_id="area_123", name="Q1 Goals")
client.work.queue_decision(
    title="Choose database",
    options=["PostgreSQL", "SQLite", "DuckDB"],
)
```

### Graph (7 operations)

```python
client.graph.create(type="person", name="Alice", role="engineer")
client.graph.link(source="node_1", target="node_2", relation="works_with")
client.graph.search(query="engineers")
client.graph.neighbors(id="node_1", direction="outbound")
client.graph.get(id="node_1")
client.graph.unlink(source="node_1", target="node_2")
client.graph.delete(id="node_1")
```

## Agent Integration

Generate tool schemas from the SDK's type system — no manual schema maintenance.

### OpenAI

```python
from khive import Khive

client = Khive()
tools = client.tools.to_openai_tools()

# Use with openai.chat.completions.create(tools=tools, ...)
# Then execute: client.tools.execute(tool_call.function.name, args)
```

### Anthropic

```python
tools = client.tools.to_anthropic_tools()
# Use with anthropic messages.create(tools=tools, ...)
# Then execute: client.tools.execute(block.name, block.input)
```

### MCP

```python
tools = client.tools.to_mcp_tools()
```

### Schema-Only (no client needed)

```python
from khive import to_openai_tools, list_tools

names = list_tools()  # All tool names
memory_tools = to_openai_tools(services=["memory"])
```

## Async

```python
import asyncio
from khive import AsyncKhive

async def main():
    async with AsyncKhive() as client:
        result = await client.memory.recall(query="recent decisions")
        await client.communication.send(content="Update", to="team")

asyncio.run(main())
```

## Error Handling

```python
from khive import Khive
from khive._errors import AuthenticationError, RateLimitError, NotFoundError

client = Khive()
try:
    client.memory.recall(query="test")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except NotFoundError:
    print("Resource not found")
```

## Configuration

```python
client = Khive(
    api_key="your-api-key",            # or KHIVE_API_KEY env var
    base_url="https://custom.api",      # or KHIVE_BASE_URL env var
    timeout=30.0,                       # request timeout (seconds)
    max_retries=3,                      # retries for transient errors
    default_headers={"X-Custom": "v"},  # additional headers
)
```
