casfa-client 0.1.2

CASFA (Content-Addressable Storage for Agents) Python SDK

CASFA Python SDK

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

Installation

pip install casfa-client

Quick Start

Agent Token Authentication

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

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

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]:

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

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

# Run tests
pytest

# Type check
mypy casfa

# Lint
ruff check casfa

License

MIT