This document contains key architectural decisions, constraints, and operational context for engineers and AI agents working on the Actos Python SDK (actos).
The backend (actos-dev/backend) is currently undergoing Faz 18.A development.
Rule of Truth: GET /openapi.json is the sole authority. Do NOT invent endpoints, parameters, or schemas that do not exist in the spec.
The OpenAPI specification is tracked in the repository at:
../actos-backend/docs/openapi.json
(Absolute path: /home/efe/Documents/actos/actos-backend/docs/openapi.json).
You do not need to spin up the backend server to inspect or generate types.
The following items are explicitly deferred and must remain unchecked ([ ]) in python/PLAN.md:
| Item | Location in PLAN.md | Reason |
|---|---|---|
inbox.* and verifications.* |
Faz 13.B | Endpoint not yet implemented in backend |
actors.update_me's avatar parameter |
Faz 6 | Backend avatar support is part of 18.A |
feed.list's actor_type parameter |
Faz 9 | Backend feed actor_type filtering is part of 18.A |
Once backend Faz 18.A is merged, types will be regenerated from the updated spec and these features will be implemented in a follow-up pass.
The SDK provides both synchronous (Actos) and asynchronous (AsyncActos) interfaces with identical ergonomics.
- Async as Source of Truth:
- All client logic, transport mechanics, and resource bindings are written first and exclusively as async under
_async/(e.g.,actos/_transport/_async.py,actos/resources/_async/).
- All client logic, transport mechanics, and resource bindings are written first and exclusively as async under
- Sync is Generated:
- Synchronous code under
_sync/(e.g.,actos/_transport/_sync.py,actos/resources/_sync/) is automatically generated/transformed byscripts/unasync.py. - Never manually maintain duplicate sync files. Any manual edits in
_sync/will be overwritten.
- Synchronous code under
- CI Check:
- CI runs
python scripts/unasync.py --checkto prevent divergence between async sources and sync targets.
- CI runs
- Unified Top-Level Export:
- Both
Actos(sync) andAsyncActos(async) clients are exported fromactos.
- Both
- Types are generated into
actos/types.pyusingdatamodel-code-generatortargeting../actos-backend/docs/openapi.json. - Settings:
- Pydantic v2 target (
ConfigDict(extra="allow")for forward compatibility). - Snake-case field preservation.
from __future__ import annotations.
- Pydantic v2 target (
actos/types.pyis committed to the repository so consumers installing via git do not need code generation dependencies.actos/types.pyMUST NEVER be edited manually.
- Errors are strictly dispatched by the RFC 9457
codestring, not by HTTP status code alone. 404 NOT_FOUNDand410 GONEare separate classes (NotFoundErrorvs.GoneError).- Every API error carries
request_id,code,status, anddetail. - Format:
[{status} {code}] {detail} (request_id={request_id}). - Unknown codes fall back gracefully to
ActosAPIError.
- Package & Environment Management:
uvuv syncinstalls all dependencies and development tools.uv run ruff check .runs linter.uv run ruff format .formats code (line-length: 100).uv run mypy actosruns strict type checking.uv run pytestruns test suite.
- Python Version Target: Python 3.10+ (supporting 3.10, 3.11, 3.12, 3.13).
- License: Apache-2.0.