casfa-client 0.1.5
CASFA (Content-Addressable Storage for Agents) Python SDK
Requires Python: >=3.11
Keywords: casfa, cas, content-addressable, storage, agents

# CASFA Python SDK

Python client for CASFA (Content-Addressable Storage for Agents).

## Installation

```bash
pip install casfa-client
```

## Quick Start

### Agent Token Authentication

```python
import asyncio
from casfa import create_casfa_client, CasfaClientConfig, TokenAuthConfig

async def main():
    # Create client with agent token
    client = create_casfa_client(CasfaClientConfig(
        base_url="https://casfa.example.com",
        auth=TokenAuthConfig(type="token", token="casfa_xxx"),
        realm_id="user:ABC123",
    ))

    # Get realm usage
    result = await client.realm.get_usage()
    if result.ok:
        print(f"Nodes: {result.data.node_count}")
        print(f"Bytes: {result.data.total_bytes}")
    else:
        print(f"Error: {result.error.message}")

    # List depots
    result = await client.depots.list()
    if result.ok:
        for depot in result.data.items:
            print(f"Depot: {depot.title} (v{depot.version})")

    await client.close()

asyncio.run(main())
```

### Ticket Authentication

```python
from casfa import create_casfa_client, CasfaClientConfig, TicketAuthConfig

async def process_with_ticket(ticket_id: str):
    client = create_casfa_client(CasfaClientConfig(
        base_url="https://casfa.example.com",
        auth=TicketAuthConfig(type="ticket", ticket_id=ticket_id),
    ))

    # Read nodes allowed by ticket scope
    result = await client.nodes.get(key="node:abc123...")
    if result.ok:
        data = result.data  # bytes
        # Process data...

    # Commit output
    result = await client.tickets.commit(
        ticket_id=ticket_id,
        output="node:result123...",
    )

    await client.close()
```

## API Reference

### Client Creation

```python
from casfa import create_casfa_client, CasfaClientConfig

client = create_casfa_client(CasfaClientConfig(
    base_url="https://casfa.example.com",
    auth=auth_config,  # TokenAuthConfig, TicketAuthConfig, etc.
    realm_id="user:ABC123",  # Optional
))
```

### API Namespaces

| Namespace | Description |
|-----------|-------------|
| `client.oauth` | OAuth/Cognito authentication |
| `client.auth` | AWP clients and Agent tokens |
| `client.admin` | Admin user management |
| `client.mcp` | MCP JSON-RPC tool calls |
| `client.realm` | Realm info and usage |
| `client.tickets` | Ticket management |
| `client.depots` | Depot management |
| `client.nodes` | Node storage operations |

### Result Pattern

All API methods return `FetchResult[T]`:

```python
result = await client.tickets.create(...)

if result.ok:
    ticket = result.data  # TicketInfo
    print(ticket.ticket_id)
else:
    error = result.error  # CasfaError
    print(f"Error: {error.code} - {error.message}")
```

### Authentication Types

| Type | Config | Header |
|------|--------|--------|
| Agent Token | `TokenAuthConfig` | `AgentToken {token}` |
| Ticket | `TicketAuthConfig` | `Ticket {ticketId}` |
| User OAuth | `UserAuthConfig` | `Bearer {accessToken}` |
| P256 (AWP) | `P256AuthConfig` | `X-AWP-*` headers |

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type check
mypy casfa

# Lint
ruff check casfa
```

## License

MIT