# cybergis/rs-embed architecture

> Architecture diagram of the GitHub repository cybergis/rs-embed, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cybergis/rs-embed
- Repository: https://github.com/cybergis/rs-embed

## Overview

rs-embed is a Python library and API for producing remote-sensing foundation-model embeddings from geographic/time requests or user-supplied imagery. The principal workflow is request specification → provider imagery fetch → model input preparation/inference → embedding result; batch and export workflows add orchestration and output writing. The README documents these capabilities, while sampled source/index evidence supports selected internal calls. Some API and model implementations were not fully sampled, so uncertain links are omitted.

Main entry points: [`src/rs_embed/api.py`](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/api.py) (Public API), [`src/rs_embed/embedders`](https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/embedders) (Model adapters), [`src/rs_embed/providers/fetch.py`](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/providers/fetch.py) (Fetch and normalize), [`src/rs_embed/pipelines/inference.py`](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/pipelines/inference.py) (Export inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Public interface"]
  node_api["Public API<br/>[api.py]"]
  node_cli["Command line<br/>[cli.py]"]
end

subgraph group_request["Request and runtime"]
  node_specs["Request specs<br/>[specs.py]"]
  node_validation["Input validation<br/>[validation.py]"]
  node_runtime["Embedder runtime<br/>[runtime.py]"]
  node_shape["Shape preparation<br/>[shape.py]"]
  node_tiling["Tiling and stitching<br/>[tiling.py]"]
end

subgraph group_imagery["Imagery access"]
  node_resolution["Provider selection<br/>[resolution.py]"]
  node_providers["Provider adapters"]
  node_fetch["Fetch and normalize<br/>[fetch.py]"]
  node_inspection["Patch inspection<br/>[inspection.py]"]
end

subgraph group_models["Model execution"]
  node_registry["Model registry<br/>[registry.py]"]
  node_catalog["Model catalog<br/>[catalog.py]"]
  node_adapters["Model adapters"]
  node_vendor["Model architectures"]
  node_embedding["Embedding result<br/>[embedding.py]"]
end

subgraph group_exports["Batch and export"]
  node_inference["Export inference<br/>[inference.py]"]
  node_exporter["Batch exporter<br/>[exporter.py]"]
  node_writers["Output writers<br/>[writers.py]"]
end

node_user(("Python caller"))
node_gee["Google Earth Engine"]
node_own_data(("User imagery"))

node_user -->|"requests embeddings"| node_api
node_user -.->|"runs commands"| node_cli
node_api -->|"accepts specs"| node_specs
node_api -->|"queries models"| node_registry
node_api -->|"requests patches"| node_fetch
node_api -->|"inspects patches"| node_inspection
node_api -.->|"starts exports"| node_exporter
node_api -.->|"dispatches inference"| node_runtime
node_api -.->|"runs batch inference"| node_inference
node_registry -->|"loads catalog"| node_catalog
node_runtime -->|"resolves model"| node_registry
node_runtime -->|"dispatches model"| node_adapters
node_adapters -.->|"uses architectures"| node_vendor
node_adapters -->|"fetches model input"| node_fetch
node_adapters -->|"prepares input"| node_shape
node_own_data -->|"supplies imagery"| node_api
node_resolution -->|"resolves backend"| node_providers
node_providers -->|"fetches imagery"| node_gee
node_fetch -->|"calls provider"| node_providers
node_fetch -->|"checks patches"| node_inspection
node_tiling -->|"uses shape helpers"| node_shape
node_exporter -->|"invokes inference"| node_inference
node_exporter -->|"writes outputs"| node_writers
node_inference -->|"tiles inputs"| node_tiling
node_inference -->|"returns embeddings"| node_embedding

click node_api "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/api.py"
click node_cli "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/cli.py"
click node_specs "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/specs.py"
click node_validation "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/validation.py"
click node_runtime "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/runtime.py"
click node_registry "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/registry.py"
click node_catalog "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/embedders/catalog.py"
click node_adapters "https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/embedders"
click node_vendor "https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/embedders/_vendor"
click node_embedding "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/embedding.py"
click node_resolution "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/providers/resolution.py"
click node_providers "https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/providers"
click node_fetch "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/providers/fetch.py"
click node_inspection "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/inspection.py"
click node_shape "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/shape.py"
click node_tiling "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/tiling.py"
click node_inference "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/pipelines/inference.py"
click node_exporter "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/pipelines/exporter.py"
click node_writers "https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/writers.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_api,node_cli,node_own_data toneBlue
class node_specs,node_validation,node_runtime,node_shape,node_tiling toneAmber
class node_resolution,node_providers,node_fetch,node_inspection toneMint
class node_registry,node_catalog,node_adapters,node_vendor,node_embedding toneRose
class node_inference,node_exporter,node_writers,node_user,node_gee toneIndigo
```

## Components

### Public interface

- [Public API](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/api.py): `src/rs_embed/api.py`
- [Command line](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/cli.py): `src/rs_embed/cli.py`

### Request and runtime

- [Request specs](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/specs.py): `src/rs_embed/core/specs.py`
- [Input validation](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/validation.py): `src/rs_embed/core/validation.py`
- [Embedder runtime](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/runtime.py): `src/rs_embed/tools/runtime.py`
- [Shape preparation](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/shape.py): `src/rs_embed/tools/shape.py`
- [Tiling and stitching](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/tiling.py): `src/rs_embed/tools/tiling.py`

### Imagery access

- [Provider selection](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/providers/resolution.py): `src/rs_embed/providers/resolution.py`
- [Provider adapters](https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/providers): `src/rs_embed/providers`
- [Fetch and normalize](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/providers/fetch.py): `src/rs_embed/providers/fetch.py`
- [Patch inspection](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/tools/inspection.py): `src/rs_embed/tools/inspection.py`

### Model execution

- [Model registry](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/registry.py): `src/rs_embed/core/registry.py`
- [Model catalog](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/embedders/catalog.py): `src/rs_embed/embedders/catalog.py`
- [Model adapters](https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/embedders): `src/rs_embed/embedders`
- [Model architectures](https://github.com/cybergis/rs-embed/tree/main/src/rs_embed/embedders/_vendor): `src/rs_embed/embedders/_vendor`
- [Embedding result](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/core/embedding.py): `src/rs_embed/core/embedding.py`

### Batch and export

- [Export inference](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/pipelines/inference.py): `src/rs_embed/pipelines/inference.py`
- [Batch exporter](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/pipelines/exporter.py): `src/rs_embed/pipelines/exporter.py`
- [Output writers](https://github.com/cybergis/rs-embed/blob/main/src/rs_embed/writers.py): `src/rs_embed/writers.py`

### Other components

- **Python caller**
- **Google Earth Engine**
- **User imagery**

## Connections

- Python caller → Public API: requests embeddings
- Python caller → Command line: runs commands
- Public API → Request specs: accepts specs (evidence: `src/rs_embed/api.py`)
- Public API → Model registry: queries models (evidence: `src/rs_embed/api.py`)
- Public API → Fetch and normalize: requests patches (evidence: `src/rs_embed/api.py`)
- Public API → Patch inspection: inspects patches (evidence: `src/rs_embed/api.py`)
- Public API → Batch exporter: starts exports (evidence: `src/rs_embed/api.py`)
- Public API → Embedder runtime: dispatches inference (evidence: `src/rs_embed/api.py`)
- Public API → Export inference: runs batch inference
- Model registry → Model catalog: loads catalog (evidence: `src/rs_embed/core/registry.py`)
- Embedder runtime → Model registry: resolves model (evidence: `src/rs_embed/tools/runtime.py`)
- Embedder runtime → Model adapters: dispatches model (evidence: `src/rs_embed/tools/runtime.py`)
- Model adapters → Model architectures: uses architectures (evidence: `src/rs_embed/embedders/onthefly_prithvi.py`)
- Model adapters → Fetch and normalize: fetches model input (evidence: `src/rs_embed/embedders/base.py`)
- Model adapters → Shape preparation: prepares input (evidence: `src/rs_embed/embedders/base.py`)
- User imagery → Public API: supplies imagery
- Provider selection → Provider adapters: resolves backend (evidence: `src/rs_embed/providers/resolution.py`)
- Provider adapters → Google Earth Engine: fetches imagery (evidence: `src/rs_embed/providers/__init__.py`)
- Fetch and normalize → Provider adapters: calls provider (evidence: `src/rs_embed/providers/fetch.py`)
- Fetch and normalize → Patch inspection: checks patches (evidence: `src/rs_embed/providers/fetch.py`)
- Tiling and stitching → Shape preparation: uses shape helpers (evidence: `src/rs_embed/tools/tiling.py`)
- Batch exporter → Export inference: invokes inference (evidence: `src/rs_embed/pipelines/exporter.py`)
- Batch exporter → Output writers: writes outputs (evidence: `src/rs_embed/pipelines/exporter.py`)
- Export inference → Tiling and stitching: tiles inputs (evidence: `src/rs_embed/pipelines/inference.py`)
- Export inference → Embedding result: returns embeddings (evidence: `src/rs_embed/pipelines/inference.py`)