Python SDK¶

Official Python client for the CloMan API.

Installation¶

pip install cloman

Requires Python 3.9+ and installs httpx as the only dependency.

Client Classes¶

`CloMan` (synchronous)¶

from cloman import CloMan

client = CloMan(
    api_key="cloman_...",       # Required
    base_url="https://api.cloman.app",  # Default
    timeout=30.0,                # Seconds
    max_retries=3,               # Retries on 5xx
)

Parameter	Type	Default	Description
`api_key`	`str`	—	Your CloMan API key (required).
`base_url`	`str`	`https://api.cloman.app`	API base URL. Override for self-hosted.
`timeout`	`float`	`30.0`	Request timeout in seconds.
`max_retries`	`int`	`3`	Max retries on 5xx server errors.

`client.decide()`¶

result = client.decide(
    context="Should we approve this refund?",
    action_type="approval",      # Default: "general"
    data={"amount": 49.99},      # Default: {}
)

Parameter	Type	Default	Description
`context`	`str`	—	The question or situation (required).
`action_type`	`str`	`"general"`	Type of action.
`data`	`dict`	`{}`	Action-specific structured data.

Returns a DecisionResponse.

Context Manager¶

with CloMan(api_key="cloman_...") as client:
    result = client.decide(context="...")
# Connection closed automatically

`client.close()`¶

Closes the underlying HTTP connection. Called automatically when using with.

`AsyncCloMan` (asynchronous)¶

from cloman import AsyncCloMan

async with AsyncCloMan(api_key="cloman_...") as client:
    result = await client.decide(context="...")

Same constructor parameters and decide() signature as CloMan, but all methods are async.

Response Model¶

`DecisionResponse`¶

Attribute	Type	Description
`decision_id`	`str`	Unique decision identifier.
`clone_id`	`str`	Clone that made the decision.
`clone_name`	`str`	Human-readable clone name.
`decision`	`str`	The clone's recommendation.
`reasoning`	`str`	Explanation for the decision.
`confidence`	`float`	Confidence score (0.0–1.0).
`confidence_level`	`str`	`high`, `medium`, or `low`.
`requires_human_review`	`bool`	Whether human review is recommended.
`was_escalated`	`bool`	Whether guardrails triggered escalation.
`alternatives_considered`	`list[dict]`	Other options considered.
`processing_time_ms`	`float`	Processing time in milliseconds.
`created_at`	`str`	ISO 8601 timestamp.

Exceptions¶

All exceptions inherit from CloManError:

CloManError
├── AuthenticationError    (401)
├── AuthorizationError     (403)
├── NotFoundError          (404)
├── ValidationError        (422)
├── RateLimitError         (429)  — has .retry_after
├── ServerError            (5xx)
└── TimeoutError           (timeout)

Every exception has these attributes:

Attribute	Type	Description
`message`	`str`	Human-readable error message.
`code`	`str`	Machine-readable error code.
`status`	`int`	HTTP status code.
`details`	`dict`	Additional error details.
`request_id`	`str \\| None`	Request ID for debugging.

Example¶

from cloman import CloMan
from cloman._exceptions import AuthenticationError, RateLimitError

client = CloMan(api_key="cloman_...")
try:
    result = client.decide(context="...")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after}")
except CloManError as e:
    print(f"API error [{e.code}]: {e.message}")

Type Safety¶

The SDK ships with py.typed (PEP 561) — full type checking works out of the box with mypy, pyright, and IDEs.