# superb-nightwolf/googleagentaicapability architecture

> Architecture diagram of the GitHub repository superb-nightwolf/googleagentaicapability, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/superb-nightwolf/googleagentaicapability
- Repository: https://github.com/superb-nightwolf/googleagentaicapability

## Overview

#### Purpose and entry points
This is a config-driven Python capability for running, logging, comparing, and selecting Google Vertex AI Experiment runs. Its primary training entry point is `mlops/experiments/experiment_run.py` (shown in the README tree); comparison without retraining uses `mlops/experiments/compare_runs.py`. Training behavior is selected dynamically from YAML rather than imported as a fixed model implementation.

#### Configuration and runtime dispatch
`mlops/experiments/config.py` loads and validates the experiment configuration, including GCP project/location, experiment identity, training callable, logging strategy, and champion-selection policy. `mlops/experiments/config.yaml` is the default package configuration. The configured `training.module` and `training.function` are dynamically loaded and invoked through `mlops/experiments/utils/training_loader.py`.

#### Experiment and run lifecycle
`mlops/experiments/vertex_experiment.py` owns reusable parent-experiment access via `aiplatform.Experiment.get_or_create()`. `mlops/experiments/vertex_experiment_run.py` creates a persistent `ExperimentRun`, attaches it as the active SDK run with `aiplatform.start_run(..., resume=True)`, and ends or fails it through the package-level Vertex SDK API. This separates durable run creation from process-local active-session control.

#### Training and logging pipeline
`mlops/experiments/experiment_run.py` orchestrates the primary flow: load config, create/start run, optionally enable autologging, execute configured training, explicitly log the returned result, close the run, and optionally select a champion. Training returns a plain dictionary containing model, curated parameters, final metrics, optional classification/time-series data, model metadata, and input examples. Explicit logging remains the authoritative path for custom values and artifacts.

#### Autologging boundary
`mlops/experiments/experiment_autolog.py` enables/disables process-global Vertex SDK autologging around training only. It is activated after the target run starts, ensuring automatic framework telemetry attaches to that run. Because autologging is global mutable process state, it is disabled after training or run completion to prevent leakage into later workloads.

#### Model artifact and lineage handling
`mlops/experiments/utils/model_logging.py` implements configurable model logging. Native mode uses `ExperimentRun.log_model()` for SDK-supported flavors such as scikit-learn, XGBoost, and TensorFlow. Artifact mode, or `auto` fallback for unsupported models, serializes the model to Cloud Storage and creates a Vertex ML Metadata `system.Model` artifact plus execution association. This is the principal compatibility boundary between framework-specific model objects and Vertex lineage.

#### Run comparison and champion promotion
`mlops/experiments/experiment_comparison.py` retrieves experiment-run DataFrames, ranks completed runs using `metric.<name>`, marks champion/challenger state through run parameters, and writes/reads a champion manifest. `mlops/experiments/compare_runs.py` exposes this selection flow independently of training. The manifest is stored in the staging GCS bucket and supplies the winning model artifact URI to downstream Model Registry workflows.

#### Infrastructure and external services
The runtime is Python with `google-cloud-aiplatform`, including the autologging extra when enabled. It requires Google Cloud Vertex AI Experiments, Vertex ML Metadata, and Cloud Storage; authentication uses Application Default Credentials and IAM must permit Vertex/metadata writes plus staging-bucket access. Example executable integrations are under `mlops/experiments/examples/`, including supported scikit-learn and fallback LightGBM paths.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_train_entry["Training entry point<br/>Python orchestrator"]
  node_compare_entry["Comparison entry point<br/>Python CLI"]
end

subgraph group_runtime["Experiment runtime"]
  node_config["Config loader<br/>validated YAML config"]
  node_default_config["Default configuration<br/>YAML"]
  node_training_loader["Dynamic training loader<br/>runtime dispatcher"]
  node_training_callable["Configured training<br/>user training callable"]
  node_parent_experiment["Parent experiment access<br/>Vertex experiment adapter"]
  node_run_lifecycle["Run lifecycle<br/>Vertex run adapter"]
end

subgraph group_logging["Logging and lineage"]
  node_autologging["Autologging boundary<br/>process-global SDK control"]
  node_explicit_logging["Explicit result logging<br/>authoritative logger"]
  node_model_logging["Model logging<br/>model compatibility layer"]
end

subgraph group_selection["Comparison and promotion"]
  node_comparison["Run comparison<br/>ranking and promotion"]
  node_champion_manifest["Champion manifest<br/>GCS manifest"]
end

subgraph group_cloud["Google Cloud services"]
  node_vertex_experiments[("Vertex AI Experiments<br/>managed experiment service")]
  node_vertex_metadata[("Vertex ML Metadata<br/>lineage service")]
  node_gcs[("Cloud Storage staging bucket<br/>artifact and manifest storage")]
  node_model_registry["Downstream Model Registry<br/>consumer workflow"]
end

node_train_entry -->|"loads"| node_config
node_config -->|"defaults"| node_default_config
node_train_entry -->|"gets or creates"| node_parent_experiment
node_parent_experiment -->|"uses"| node_vertex_experiments
node_train_entry -->|"creates and starts"| node_run_lifecycle
node_run_lifecycle -->|"persists run"| node_vertex_experiments
node_train_entry -->|"scopes around training"| node_autologging
node_train_entry -->|"dispatches"| node_training_loader
node_training_loader -->|"dynamically invokes"| node_training_callable
node_training_callable -->|"returns result"| node_explicit_logging
node_explicit_logging -->|"logs to active run"| node_run_lifecycle
node_explicit_logging -->|"logs model"| node_model_logging
node_model_logging -->|"native model logging"| node_vertex_experiments
node_model_logging -->|"artifact fallback"| node_gcs
node_model_logging -->|"creates model lineage"| node_vertex_metadata
node_train_entry -.->|"optional selection"| node_comparison
node_compare_entry -->|"loads"| node_config
node_compare_entry -->|"runs selection"| node_comparison
node_comparison -->|"retrieves and marks runs"| node_vertex_experiments
node_comparison -->|"writes and reads"| node_champion_manifest
node_champion_manifest -->|"stored in"| node_gcs
node_champion_manifest -->|"supplies artifact URI"| node_model_registry

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_train_entry,node_compare_entry toneBlue
class node_config,node_default_config,node_training_loader,node_training_callable,node_parent_experiment,node_run_lifecycle toneAmber
class node_autologging,node_explicit_logging,node_model_logging toneMint
class node_comparison,node_champion_manifest toneRose
class node_vertex_experiments,node_vertex_metadata,node_gcs,node_model_registry toneIndigo
```

## Components

### Entry points

- **Training entry point**: Python orchestrator · Runs the configured experiment lifecycle.
- **Comparison entry point**: Python CLI · Selects a champion without retraining.

### Experiment runtime

- **Config loader**: validated YAML config · Loads experiment, training, logging, and selection settings.
- **Default configuration**: YAML
- **Dynamic training loader**: runtime dispatcher · Imports and invokes the configured training callable.
- **Configured training**: user training callable · Returns model, parameters, metrics, metadata, and examples.
- **Parent experiment access**: Vertex experiment adapter · Gets or creates the reusable parent experiment.
- **Run lifecycle**: Vertex run adapter · Creates persistent runs and controls the active SDK session.

### Logging and lineage

- **Autologging boundary**: process-global SDK control · Enables telemetry only while the target run is active.
- **Explicit result logging**: authoritative logger · Logs returned custom values and artifacts.
- **Model logging**: model compatibility layer · Uses native SDK logging or artifact lineage fallback.

### Comparison and promotion

- **Run comparison**: ranking and promotion · Ranks completed runs and maintains champion state.
- **Champion manifest**: GCS manifest · Publishes the winning model artifact URI.

### Google Cloud services

- **Vertex AI Experiments**: managed experiment service
- **Vertex ML Metadata**: lineage service
- **Cloud Storage staging bucket**: artifact and manifest storage
- **Downstream Model Registry**: consumer workflow · Consumes the promoted model artifact URI.

## Connections

- Training entry point → Config loader: loads
- Config loader → Default configuration: defaults
- Training entry point → Parent experiment access: gets or creates
- Parent experiment access → Vertex AI Experiments: uses
- Training entry point → Run lifecycle: creates and starts
- Run lifecycle → Vertex AI Experiments: persists run
- Training entry point → Autologging boundary: scopes around training
- Training entry point → Dynamic training loader: dispatches
- Dynamic training loader → Configured training: dynamically invokes
- Configured training → Explicit result logging: returns result
- Explicit result logging → Run lifecycle: logs to active run
- Explicit result logging → Model logging: logs model
- Model logging → Vertex AI Experiments: native model logging
- Model logging → Cloud Storage staging bucket: artifact fallback
- Model logging → Vertex ML Metadata: creates model lineage
- Training entry point → Run comparison: optional selection
- Comparison entry point → Config loader: loads
- Comparison entry point → Run comparison: runs selection
- Run comparison → Vertex AI Experiments: retrieves and marks runs
- Run comparison → Champion manifest: writes and reads
- Champion manifest → Cloud Storage staging bucket: stored in
- Champion manifest → Downstream Model Registry: supplies artifact URI