Skip to content
forecast-engine

adapters

Papel na engine

Adapters são a camada de integração do módulo crítico: traduzem formatos externos para o domínio e preservam as invariantes que sustentam a operação da plataforma.

adapters.demand_adapter

Funções principais:

  • to_domain_series_key / to_contract_series_key
  • to_domain_demand_observation / to_contract_demand_observation
  • to_domain_demand_series / to_contract_demand_series
  • to_domain_demand_quantity / to_contract_demand_quantity
  • to_domain_organization_id / to_contract_organization_id
  • to_domain_external_key / to_contract_external_key
  • to_domain_time_grain / to_contract_time_grain
  • to_domain_period_start / to_contract_period_start
  • parse_decimal

Responsabilidade:

  • mapear contratos de demanda para domínio mantendo UTC, enums e decimais.

adapters.modeling_adapter

Funções principais:

  • mapeamento bidirecional de:
    • ModelName
    • WindowSpec
    • LagSpec
    • HorizonSpec
    • MetricSpec
    • EvaluatorSpec
    • StrategySpec
    • ModelVersion
    • ModelInstance
    • ModelDefinition
  • conversão de status e direções:
    • to_domain_model_version_status / to_contract_model_version_status
    • to_domain_model_instance_status / to_contract_model_instance_status
    • to_domain_metric_direction / to_contract_metric_direction

Responsabilidade:

  • reconstruir agregado completo de ModelDefinition, incluindo versões e instâncias.
  • preservar o vínculo ModelInstance.model_version -> ModelVersion.
  • preservar metadados operacionais da instância, como registered_model_name, registered_model_version, serving_alias e promoted_at.

adapters.operations_adapter

Funções principais:

  • to_contract_promotion_audit_record
  • to_domain_promotion_audit_record

Responsabilidade:

  • serializar e reconstruir PromotionAuditRecord sem vazar detalhes de persistência para a camada de aplicação.

adapters.strategy_config

Componentes principais:

  • StrategyConfigView
  • create_strategy_config_view(strategy_spec)

Responsabilidade:

  • expor leitura normalizada e read-only de StrategySpec.params_schema, em especial training_mode, com defaults estáveis e erros explícitos para config inválida.

adapters.forecasting_adapter

Funções principais:

  • to_domain_forecast_point_value / to_contract_forecast_point_value
  • to_domain_prediction_interval / to_contract_prediction_interval
  • to_domain_forecast_point / to_contract_forecast_point
  • to_domain_forecast_run / to_contract_forecast_run
  • to_domain_forecast_run_status / to_contract_forecast_run_status

Responsabilidade:

  • preservar estado do ForecastRun, incluindo metadata de fallback degradado.

adapters.columnar.polars_mapper

PolarsDomainMapper

Métodos:

  • demand_series_to_frame(series)
  • frame_to_demand_series(frame)
  • forecast_run_to_frame(run)
  • frame_to_forecast_points(frame, grain, expected_uom)

Características:

  • valida colunas obrigatórias;
  • valida tipos Polars esperados;
  • converte datas para UTC;
  • garante coerência de UOM e intervalos de previsão.

adapters.columnar.parquet_store

PolarsParquetStore

Métodos:

  • write_frame(frame, destination, schema_version) -> str
  • read_frame(source, expected_schema_version)

Características:

  • persiste metadado de versão com __schema_version;
  • valida versão ao carregar;
  • falha se metadado ausente/incompatível.

adapters.mlflow.tracker

MlflowExperimentTracker

Métodos:

  • start_run(...) -> str
  • start_batch_run(...) -> str
  • log_params(run_id, params)
  • log_tags(run_id, tags)
  • log_metrics(run_id, metrics)
  • log_artifact(run_id, artifact_uri)
  • end_run(run_id, status)

Características:

  • cria experimento automaticamente se não existir;
  • adiciona tags de contexto de negócio por run, incluindo training_scope;
  • em batch, registra series_count e a identidade das séries do lote;
  • normaliza status final para valores aceitos pelo MLflow.

adapters.mlflow.registry

MlflowModelRegistryAdapter

Métodos:

  • register_model_version(...) -> RegisteredModelVersion
  • promote_model_version(...)
  • deprecate_model_version(...)
  • resolve_serving_target(...) -> ServingTarget

Características:

  • usa convenção estável de nome por organização, definição, série e estratégia;
  • cria o registered model automaticamente se ainda não existir;
  • registra tags de contexto operacional, incluindo domain_version, artifact_uri e promotion_decision_timestamp;
  • usa alias champion como superfície padrão de serving.

adapters.mlflow.inference

MlflowForecastObservabilityAdapter

Método:

  • record_forecast(telemetry)

Características:

  • cria uma run dedicada por execução de forecast;
  • registra tags de versão requisitada/executada e fallback;
  • publica métricas de horizonte, volume previsto, duração e sucesso.

adapters.persistence.file_store

Componentes:

  • FileSystemModelingRepository
  • FileSystemForecastingRepository
  • LocalArtifactStore

Características:

  • persistência durável via JSON usando contratos msgspec;
  • path convention estável por organização, definição, série, estratégia e versão;
  • auditoria de promoção persistida fora do agregado de domínio;
  • armazenamento local de artefatos com URI file:// auditável.