# geponce/geo-embeddings-agents architecture

> Architecture diagram of the GitHub repository geponce/geo-embeddings-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geponce/geo-embeddings-agents
- Repository: https://github.com/geponce/geo-embeddings-agents

## Overview

geo-embeddings turns Earth Engine satellite embeddings and Cropland Data Layer labels into validated land-cover results, similarity search, and change insights on Databricks. The main workflow samples and labels pixels, trains and spatially validates a classifier, builds a county-wide embedding grid, then supports vector search and H3 change rollups. A Claude agent team exposes these results through read-only tools and checks claims against validation evidence. Edges use README workflow statements or source-index references; several implementation details were not excerpted, so their links are omitted where evidence is insufficient.

Main entry points: [`src/geo_embeddings/agent_tools.py`](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/agent_tools.py) (Read-only tools), [`src/geo_embeddings/build_grid.py`](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/build_grid.py) (County grid builder), [`src/geo_embeddings/sampling.py`](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/sampling.py) (Labeled sampling), [`src/geo_embeddings/build_samples.py`](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/build_samples.py) (Sample builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Earth Engine ingest"]
  node_auth["EE authentication<br/>[ee_auth.py]"]
  node_embedding["Embedding access<br/>[embeddings.py]"]
  node_classmap["CDL class mapping<br/>[classes.py]"]
  node_sampling["Labeled sampling<br/>[sampling.py]"]
  node_samplebuild["Sample builder<br/>[build_samples.py]"]
  node_gridbuild["County grid builder<br/>[build_grid.py]"]
end

subgraph group_analysis["Model and validation"]
  node_classifier["Random Forest<br/>[train_baseline.py]"]
  node_spatial["Spatial blocks<br/>[spatial.py]"]
  node_validation["Cross-validation<br/>[validation.py]"]
  node_tracking["MLflow tracking<br/>[tracking.py]"]
end

subgraph group_insights["Search and change"]
  node_change["Embedding change<br/>[change.py]"]
  node_changeanalysis["Change analysis<br/>[change_analysis.py]"]
  node_search["Vector Search<br/>[search.py]"]
  node_h3["H3 rollup<br/>[h3_map.py]"]
  node_sql["SQL access<br/>[dbsql.py]"]
end

subgraph group_agents["Agent interface"]
  node_agenttools["Read-only tools<br/>[agent_tools.py]"]
  node_sqlguard["SQL guard<br/>[sql_guard.py]"]
  node_team["Planner and specialists<br/>[team.py]"]
  node_runner["Agent CLI<br/>[run.py]"]
end

node_user(("Analyst"))
node_ee["Earth Engine"]
node_databricks["Databricks"]
node_claude["Claude API"]
node_delta[("Delta tables")]

node_user -->|"build samples"| node_samplebuild
node_samplebuild -->|"samples with"| node_sampling
node_sampling -->|"reads vectors"| node_embedding
node_sampling -->|"groups labels"| node_classmap
node_samplebuild -->|"initializes"| node_auth
node_auth -->|"authenticates"| node_ee
node_sampling -->|"samples data"| node_ee
node_user -->|"build grid"| node_gridbuild
node_gridbuild -->|"uses vectors"| node_embedding
node_gridbuild -->|"uses sampling"| node_sampling
node_gridbuild -->|"initializes"| node_auth
node_samplebuild -->|"loads samples"| node_delta
node_gridbuild -->|"loads grid"| node_delta
node_user -->|"train model"| node_classifier
node_classifier -->|"evaluates folds"| node_validation
node_validation -->|"builds blocks"| node_spatial
node_classifier -->|"logs runs"| node_tracking
node_classifier -->|"reads samples"| node_delta
node_user -->|"analyze change"| node_changeanalysis
node_changeanalysis -->|"computes score"| node_change
node_user -->|"find similar places"| node_search
node_search -->|"indexes grid"| node_delta
node_user -->|"roll up change"| node_h3
node_h3 -->|"queries tables"| node_sql
node_sql -->|"runs statements"| node_databricks
node_user -->|"asks question"| node_runner
node_runner -->|"starts team"| node_team
node_team -->|"dispatches tools"| node_agenttools
node_team -->|"delegates reasoning"| node_claude
node_agenttools -->|"guards SQL"| node_sqlguard
node_agenttools -->|"runs queries"| node_sql
node_agenttools -->|"queries index"| node_search
node_agenttools -->|"reads embeddings"| node_embedding
node_agenttools -->|"initializes EE"| node_auth
node_team -->|"reads results"| node_delta

click node_auth "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/ee_auth.py"
click node_embedding "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/embeddings.py"
click node_classmap "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/classes.py"
click node_sampling "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/sampling.py"
click node_samplebuild "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/build_samples.py"
click node_gridbuild "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/build_grid.py"
click node_classifier "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/train_baseline.py"
click node_spatial "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/spatial.py"
click node_validation "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/validation.py"
click node_tracking "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/tracking.py"
click node_change "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/change.py"
click node_changeanalysis "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/change_analysis.py"
click node_search "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/search.py"
click node_h3 "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/h3_map.py"
click node_sql "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/dbsql.py"
click node_agenttools "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/agent_tools.py"
click node_sqlguard "https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/sql_guard.py"
click node_team "https://github.com/geponce/geo-embeddings-agents/blob/main/agents/team.py"
click node_runner "https://github.com/geponce/geo-embeddings-agents/blob/main/agents/run.py"

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_auth,node_embedding,node_classmap,node_sampling,node_samplebuild,node_gridbuild toneBlue
class node_classifier,node_spatial,node_validation,node_tracking,node_delta toneAmber
class node_change,node_changeanalysis,node_search,node_h3,node_sql,node_claude toneMint
class node_agenttools,node_sqlguard,node_team,node_runner toneRose
class node_user,node_ee,node_databricks toneIndigo
```

## Components

### Earth Engine ingest

- [EE authentication](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/ee_auth.py): `src/geo_embeddings/ee_auth.py`
- [Embedding access](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/embeddings.py): `src/geo_embeddings/embeddings.py`
- [CDL class mapping](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/classes.py): `src/geo_embeddings/classes.py`
- [Labeled sampling](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/sampling.py): `src/geo_embeddings/sampling.py`
- [Sample builder](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/build_samples.py): `src/geo_embeddings/build_samples.py`
- [County grid builder](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/build_grid.py): `src/geo_embeddings/build_grid.py`

### Model and validation

- [Random Forest](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/train_baseline.py): `src/geo_embeddings/train_baseline.py`
- [Spatial blocks](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/spatial.py): `src/geo_embeddings/spatial.py`
- [Cross-validation](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/validation.py): `src/geo_embeddings/validation.py`
- [MLflow tracking](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/tracking.py): `src/geo_embeddings/tracking.py`

### Search and change

- [Embedding change](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/change.py): `src/geo_embeddings/change.py`
- [Change analysis](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/change_analysis.py): `src/geo_embeddings/change_analysis.py`
- [Vector Search](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/search.py): `src/geo_embeddings/search.py`
- [H3 rollup](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/h3_map.py): `src/geo_embeddings/h3_map.py`
- [SQL access](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/dbsql.py): `src/geo_embeddings/dbsql.py`

### Agent interface

- [Read-only tools](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/agent_tools.py): `src/geo_embeddings/agent_tools.py`
- [SQL guard](https://github.com/geponce/geo-embeddings-agents/blob/main/src/geo_embeddings/sql_guard.py): `src/geo_embeddings/sql_guard.py`
- [Planner and specialists](https://github.com/geponce/geo-embeddings-agents/blob/main/agents/team.py): `agents/team.py`
- [Agent CLI](https://github.com/geponce/geo-embeddings-agents/blob/main/agents/run.py): `agents/run.py`

### Other components

- **Analyst**
- **Earth Engine**
- **Databricks**
- **Claude API**
- **Delta tables**

## Connections

- Analyst → Sample builder: build samples (evidence: `README.md`)
- Sample builder → Labeled sampling: samples with (evidence: `src/geo_embeddings/build_samples.py`)
- Labeled sampling → Embedding access: reads vectors (evidence: `src/geo_embeddings/sampling.py`)
- Labeled sampling → CDL class mapping: groups labels (evidence: `src/geo_embeddings/sampling.py`)
- Sample builder → EE authentication: initializes (evidence: `src/geo_embeddings/build_samples.py`)
- EE authentication → Earth Engine: authenticates (evidence: `src/geo_embeddings/ee_auth.py`)
- Labeled sampling → Earth Engine: samples data (evidence: `README.md`)
- Analyst → County grid builder: build grid (evidence: `README.md`)
- County grid builder → Embedding access: uses vectors (evidence: `src/geo_embeddings/build_grid.py`)
- County grid builder → Labeled sampling: uses sampling (evidence: `src/geo_embeddings/build_grid.py`)
- County grid builder → EE authentication: initializes (evidence: `src/geo_embeddings/build_grid.py`)
- Sample builder → Delta tables: loads samples (evidence: `README.md`)
- County grid builder → Delta tables: loads grid (evidence: `README.md`)
- Analyst → Random Forest: train model (evidence: `README.md`)
- Random Forest → Cross-validation: evaluates folds (evidence: `src/geo_embeddings/train_baseline.py`)
- Cross-validation → Spatial blocks: builds blocks (evidence: `src/geo_embeddings/validation.py`)
- Random Forest → MLflow tracking: logs runs (evidence: `src/geo_embeddings/train_baseline.py`)
- Random Forest → Delta tables: reads samples (evidence: `README.md`)
- Analyst → Change analysis: analyze change (evidence: `README.md`)
- Change analysis → Embedding change: computes score (evidence: `src/geo_embeddings/change_analysis.py`)
- Analyst → Vector Search: find similar places (evidence: `README.md`)
- Vector Search → Delta tables: indexes grid (evidence: `README.md`)
- Analyst → H3 rollup: roll up change (evidence: `README.md`)
- H3 rollup → SQL access: queries tables (evidence: `src/geo_embeddings/h3_map.py`)
- SQL access → Databricks: runs statements (evidence: `README.md`)
- Analyst → Agent CLI: asks question (evidence: `README.md`)
- Agent CLI → Planner and specialists: starts team (evidence: `agents/run.py`)
- Planner and specialists → Read-only tools: dispatches tools (evidence: `agents/team.py`)
- Planner and specialists → Claude API: delegates reasoning (evidence: `README.md`)
- Read-only tools → SQL guard: guards SQL (evidence: `src/geo_embeddings/agent_tools.py`)
- Read-only tools → SQL access: runs queries (evidence: `src/geo_embeddings/agent_tools.py`)
- Read-only tools → Vector Search: queries index (evidence: `src/geo_embeddings/agent_tools.py`)
- Read-only tools → Embedding access: reads embeddings (evidence: `src/geo_embeddings/agent_tools.py`)
- Read-only tools → EE authentication: initializes EE (evidence: `src/geo_embeddings/agent_tools.py`)
- Planner and specialists → Delta tables: reads results (evidence: `README.md`)
