Metadata-Version: 2.4
Name: akasha-client
Version: 1.0.9
Summary: Python SDK for Akasha — The Shared Cognitive Fabric for Intelligent Agent Systems
Project-URL: Homepage, https://github.com/ocuil/akasha-public
Project-URL: Repository, https://github.com/ocuil/akasha-public
Project-URL: Documentation, https://github.com/ocuil/akasha-public/blob/main/akasha-docs/installation.md
Project-URL: Changelog, https://github.com/ocuil/akasha-public/blob/main/CHANGELOG.md
Project-URL: Docker Hub, https://hub.docker.com/r/alejandrosl/akasha
Author-email: Alejandro Sánchez Losa <dev@alejandrosl.com>
License: ASL-1.0
Keywords: agents,akasha,grpc,real-time,shared-memory
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Requires-Dist: grpcio-tools>=1.60.0
Requires-Dist: grpcio>=1.60.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: protobuf>=4.25.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Akasha Python SDK

> The official Python client for [Akasha](https://github.com/ocuil/akasha-public) — The Shared Cognitive Fabric for Intelligent Agent Systems.

[![PyPI](https://img.shields.io/pypi/v/akasha-client?color=blue)](https://pypi.org/project/akasha-client/)
[![Python](https://img.shields.io/pypi/pyversions/akasha-client)](https://pypi.org/project/akasha-client/)
[![License](https://img.shields.io/badge/License-ASL--1.0-blue.svg)](../../LICENSE)

## Installation

```bash
pip install akasha-client
```

## Quick Start

```python
from akasha import AkashaHttpClient

# Connect (auto-TLS with self-signed certs → verify_ssl=False for dev)
client = AkashaHttpClient(
    "https://localhost:7777",
    api_key="ak_your_api_key",
    verify_ssl=False,
)

# Write a record
record = client.put("agents/planner/state", {
    "status": "thinking",
    "task": "summarize document",
    "confidence": 0.85,
})

print(f"Created: {record.path} (v{record.version})")

# Read it back
state = client.get("agents/planner/state")
print(f"Status: {state.value['status']}")

# Query with glob patterns
all_states = client.query("agents/*/state")
for r in all_states:
    print(f"  {r.path}: {r.value}")

# Delete
client.delete("agents/planner/state")
client.close()
```

## CAS (Compare-And-Swap) — Optimistic Concurrency

Prevent lost updates when multiple agents write to the same path:

```python
from akasha import AkashaHttpClient, CasConflictError

client = AkashaHttpClient("https://localhost:7777", verify_ssl=False)

# Read current version
record = client.get("shared/counter")

try:
    # Only update if nobody else changed it since our read
    updated = client.put_cas(
        "shared/counter",
        {"count": record.value["count"] + 1},
        expected_version=record.version,
    )
    print(f"Updated to v{updated.version}")
except CasConflictError as e:
    print(f"Conflict! Expected v{e.expected_version}, got v{e.actual_version}")
    print(f"Current value: {e.current}")
```

## Memory Layers

Akasha organizes knowledge into four cognitive layers:

```python
from akasha import AkashaHttpClient, MemoryLayer

client = AkashaHttpClient("https://localhost:7777", verify_ssl=False)

# Working memory (volatile, 30 min TTL)
client.put(
    f"{MemoryLayer.WORKING.prefix}agent-1/scratch",
    {"current_task": "analyze"},
    ttl_seconds=MemoryLayer.WORKING.default_ttl_seconds,
)

# Episodic memory (event log, 24h TTL)
client.put(
    f"{MemoryLayer.EPISODIC.prefix}agent-1/events/2024-01-15",
    {"action": "summarized", "input_tokens": 4500},
    ttl_seconds=MemoryLayer.EPISODIC.default_ttl_seconds,
)

# Semantic memory (permanent knowledge)
client.put(
    f"{MemoryLayer.SEMANTIC.prefix}domain/users/preferences",
    {"theme": "dark", "language": "es"},
)

# Query all episodic memories
episodes = client.query(MemoryLayer.EPISODIC.glob_all)
```

## Authentication

```python
# API Key (recommended for agents)
client = AkashaHttpClient(
    "https://akasha.example.com",
    api_key="ak_live_abc123",
)

# JWT Token (for user sessions)
client = AkashaHttpClient(
    "https://akasha.example.com",
    token="eyJhbGciOiJIUzI1NiIs...",
)
```

## Context Manager

```python
with AkashaHttpClient("https://localhost:7777", verify_ssl=False) as client:
    client.put("test/hello", {"message": "world"})
    record = client.get("test/hello")
    print(record.value)
# Connection auto-closed
```

## Async Support

```python
import asyncio
from akasha import AsyncAkashaClient  # gRPC-based async client

async def main():
    async with AsyncAkashaClient("localhost:50051") as client:
        await client.put("agents/worker/status", {"busy": True})
        record = await client.get("agents/worker/status")
        print(record.value)

asyncio.run(main())
```

## API Reference

### `AkashaHttpClient`

| Method | Description |
|--------|-------------|
| `put(path, value, *, ttl_seconds, tags)` | Write a record |
| `put_cas(path, value, *, expected_version, ...)` | Write with CAS concurrency control |
| `get(path)` → `Record \| None` | Read a record |
| `delete(path)` → `bool` | Delete a record |
| `query(pattern, *, limit)` → `list[Record]` | Glob query |
| `list_agents()` → `list[dict]` | List registered agents |
| `tree()` → `dict` | Full state tree snapshot |
| `health()` → `dict` | Health check |
| `metrics()` → `dict` | Server metrics |

### `Record`

| Field | Type | Description |
|-------|------|-------------|
| `path` | `str` | Hierarchical path |
| `value` | `Any` | Stored value (auto JSON) |
| `version` | `int` | Monotonic version counter |
| `created_at` | `datetime` | Creation timestamp |
| `updated_at` | `datetime` | Last update timestamp |
| `ttl_seconds` | `float \| None` | Time-to-live |
| `tags` | `dict[str, str]` | Key-value metadata |

### `CasConflictError`

| Field | Type | Description |
|-------|------|-------------|
| `expected_version` | `int` | Version you expected |
| `actual_version` | `int` | Server's current version |
| `current` | `dict` | Current record data |

## Requirements

- Python ≥ 3.10
- `httpx` ≥ 0.27 (HTTP client)
- `grpcio` ≥ 1.60 (gRPC client)
- `msgpack` ≥ 1.0 (serialization)

## Links

- [Akasha GitHub](https://github.com/ocuil/akasha-public)
- [Docker Hub](https://hub.docker.com/r/alejandrosl/akasha)
- [Changelog](https://github.com/ocuil/akasha-public/blob/main/CHANGELOG.md)
