Skip to content

API Reference

Plugins are written against three public import surfaces:

  • firecube.ingestor.api — templates, hooks, context, and result types
  • firecube.core.api — storage, URI, time, and dataset-preparation utilities
  • firecube.ingestor.extensions — optional regridding and DuckDB helpers

Import only from these modules. Deep imports into other Firecube modules are not part of the public contract and are rejected by the plugin contract test.

  • Templates

    The template classes plugin authors subclass, and the hooks each template requires.

    Templates

  • Hooks & Lifecycle

    The full BaseIngestor hook surface: batch shaping, lifecycle, validation, and metrics hooks.

    Hooks & Lifecycle

  • Context & Results

    PluginContext, storage sessions, batch inputs, and the result and metrics types hooks receive and return.

    Context & Results

  • Exceptions

    The error types Firecube raises and plugins may raise or catch.

    Exceptions

  • Slot-Range Parallelism

    Types and methods for parallel DirectZarrIngestor writes across disjoint slot ranges.

    Slot-Range Parallelism

  • Extensions

    Optional HEALPix and lat/lon regridding helpers and DuckDB batch support.

    Extensions

  • Core Utilities

    URI parsing, filesystem access, time conversion, and netCDF/HDF5 preparation helpers from firecube.core.api.

    Core Utilities

  • Configuration

    Config dataclasses: storage, engine, template, and plugin option schemas.

    Configuration

  • CLI

    The complete firecube command tree, generated from the live CLI.

    CLI Reference

  • Observability

    Metrics, environment variables, and telemetry surfaces.

    Observability

  • Storage Drivers

    Driver capabilities and selection rules.

    Storage Drivers

  • Control-Plane Spec

    What ChunkManager writes into .firecube/ to make resume, recovery, and parallel writes safe.

    Control-Plane Spec