Skip to main content

Python reference

This tree is auto-generated by alphaswarm_docs/scripts/extract-python.ts on every CI run that touches **/*.py. The extraction pipeline is:

  1. Griffe walks the Python AST and parses signatures, type hints, docstrings, and dynamic attributes.
  2. griffe-pydantic teaches Griffe to render Pydantic model constraints, validators, and aliases — critical for FastAPI request/response models.
  3. mdxify emits MDX with Docusaurus-native admonitions and navigation generation.

The output mirrors the source tree under alphaswarm_docs/docs/reference/python/.

Top-level packages​

  • alphaswarm — quant runtime (strategy, backtest, agents, RAG, data).
  • alphaswarm_rl — RL subsystem (RLRuntime, RLComponent metaclass, etc.).
  • alphaswarm_models — ML framework, AlphaBacktestExperiment, model serving.
  • alphaswarm_controller — workload lifecycle, TerraformRuntime.
  • alphaswarm_core — shared ABCs, value types, auth filters.

Docstring style​

Standardised on Google-style docstrings. Griffe parses ReST + NumPy styles too, but mixed styles confuse downstream tooling.

def append_arrow(
    table: str,
    arrow_table: pa.Table,
    *,
    namespace: str,
    medallion_layer: Literal["bronze", "silver", "gold"],
    business_metadata: BusinessMetadata | None = None,
) -> SnapshotResult:
    """Append an Arrow table to an Iceberg table.

    The single sanctioned write path for Iceberg in AlphaSwarm. See
    AGENTS rule 3.

    Args:
        table: The Iceberg table name (without namespace prefix).
        arrow_table: The data to append.
        namespace: The medallion-qualified namespace
            (`alphaswarm_bronze_*`, `alphaswarm_silver_*`, `alphaswarm_gold_*`).
        medallion_layer: Must match the namespace prefix.
        business_metadata: Optional active-metadata block.

    Returns:
        A `SnapshotResult` with the new manifest list location and
        the snapshot id.

    Raises:
        IcebergNamespaceError: If the namespace prefix does not
            match the declared layer.
    """

Reading the generated docs​

Browse via the sidebar to the left. Each module page shows:

  • A summary line from the first paragraph of the module docstring.
  • Every public class, function, and dataclass with full signature.
  • A "Source" link back to GitHub.
  • A "Used by" cross-reference graph (Phase 6 — backed by the Codebase MCP server's symbol index).

Breaking-change detection​

The CI surface runs griffe check against every PR. Any API removal / signature change posts a comment on the PR and requires a breaking-change label + matching Changeset entry.