Skip to content

Latest commit

 

History

History
81 lines (59 loc) · 3.69 KB

NOTES.md

File metadata and controls

81 lines (59 loc) · 3.69 KB

Actos Python SDK — Engineering Notes

This document contains key architectural decisions, constraints, and operational context for engineers and AI agents working on the Actos Python SDK (actos).


1. Backend Faz 18.A Dependencies and Deferred Items (§0.2)

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.

Deferred Items (Must NOT be implemented until backend Faz 18.A lands)

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.


2. Dual Sync / Async Architecture (unasync)

The SDK provides both synchronous (Actos) and asynchronous (AsyncActos) interfaces with identical ergonomics.

Implementation Rules:

  1. 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/).
  2. Sync is Generated:
    • Synchronous code under _sync/ (e.g., actos/_transport/_sync.py, actos/resources/_sync/) is automatically generated/transformed by scripts/unasync.py.
    • Never manually maintain duplicate sync files. Any manual edits in _sync/ will be overwritten.
  3. CI Check:
    • CI runs python scripts/unasync.py --check to prevent divergence between async sources and sync targets.
  4. Unified Top-Level Export:
    • Both Actos (sync) and AsyncActos (async) clients are exported from actos.

3. Type Generation Pipeline

  • Types are generated into actos/types.py using datamodel-code-generator targeting ../actos-backend/docs/openapi.json.
  • Settings:
    • Pydantic v2 target (ConfigDict(extra="allow") for forward compatibility).
    • Snake-case field preservation.
    • from __future__ import annotations.
  • actos/types.py is committed to the repository so consumers installing via git do not need code generation dependencies.
  • actos/types.py MUST NEVER be edited manually.

4. Error Hierarchy (§4)

  • Errors are strictly dispatched by the RFC 9457 code string, not by HTTP status code alone.
  • 404 NOT_FOUND and 410 GONE are separate classes (NotFoundError vs. GoneError).
  • Every API error carries request_id, code, status, and detail.
  • Format: [{status} {code}] {detail} (request_id={request_id}).
  • Unknown codes fall back gracefully to ActosAPIError.

5. Tooling and Development Workflow

  • Package & Environment Management: uv
    • uv sync installs all dependencies and development tools.
    • uv run ruff check . runs linter.
    • uv run ruff format . formats code (line-length: 100).
    • uv run mypy actos runs strict type checking.
    • uv run pytest runs test suite.
  • Python Version Target: Python 3.10+ (supporting 3.10, 3.11, 3.12, 3.13).
  • License: Apache-2.0.