# phzwart/agentsg architecture

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

- Interactive diagram: https://gitdiagram.com/phzwart/agentsg
- Repository: https://github.com/phzwart/agentsg

## Overview

agentsg is a dependency-free crystallographic toolkit for unit-cell comparison, space-group operations, and serial-crystallography reindexing. A typical comparison computes root-form distances, optionally searches precomputed PDB cells, and exposes results through a read-only HTTP API; reindexing provides a separate workflow for matching cell settings. Space-group operations also support reflection conditions, asymmetric units, and ITA-style diagrams, while manifold utilities parse CrystFEL streams and describe cell trajectories. The README documents these capabilities; sampled source confirms portions of the API and reindexing internals, so uncertain links are omitted.

Main entry points: [`agentsg/src/agentsg/serve/handlers.py`](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/serve/handlers.py) (API handlers), [`agentsg/src/agentsg/cell/celldb.py`](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/celldb.py) (Cell database), [`agentsg/src/agentsg/serve/app.py`](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/serve/app.py) (HTTP service), [`agentsg/src/agentsg/space_groups.py`](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/space_groups.py) (Space groups)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_comparison["Cell comparison"]
  node_metric["Cell metrics<br/>[metric.py]"]
  node_reduction["Niggli reduction<br/>[reduction.py]"]
  node_rootform["Root invariants<br/>[rootform.py]"]
  node_celldb[("Cell database<br/>[celldb.py]")]
  node_neartree["Metric index<br/>[neartree.py]"]
end

subgraph group_symmetry["Space-group symmetry"]
  node_space_groups["Space groups<br/>[space_groups.py]"]
  node_setting["Group settings<br/>[setting.py]"]
  node_hall["Hall operations<br/>[hall.py]"]
  node_reflections["Reflection conditions<br/>[reflections.py]"]
  node_asu["Asymmetric units<br/>[asu.py]"]
  node_diagrams["ITA diagrams<br/>[diagrams.py]"]
end

subgraph group_reindex["Serial reindexing"]
  node_ambiguity["Reindexing ambiguity<br/>[ambiguity.py]"]
  node_canonical["Canonical operators<br/>[canonical.py]"]
  node_reindex["Reindexing<br/>[reindex.py]"]
  node_manifold["Cell manifold<br/>[manifold.py]"]
  node_stream["CrystFEL streams<br/>[crystfel_stream.py]"]
end

subgraph group_integration["Data and interface"]
  node_pdb_app["PDB database app<br/>[pdb_app.py]"]
  node_handlers["API handlers<br/>[handlers.py]"]
  node_http_app["HTTP service<br/>[app.py]"]
end

node_crystal_user(("Crystallography user"))

node_crystal_user -->|"sends requests"| node_http_app
node_http_app -->|"dispatches requests"| node_handlers
node_handlers -->|"resolves groups"| node_space_groups
node_handlers -->|"parses settings"| node_setting
node_handlers -->|"computes conditions"| node_reflections
node_handlers -->|"uses reciprocal ASU"| node_asu
node_handlers -->|"renders plates"| node_diagrams
node_handlers -->|"builds cell metrics"| node_metric
node_handlers -->|"reduces cells"| node_reduction
node_handlers -->|"compares roots"| node_rootform
node_handlers -->|"looks up cells"| node_celldb
node_http_app -->|"opens database"| node_celldb
node_celldb -->|"builds index"| node_neartree
node_pdb_app -->|"builds database"| node_celldb
node_space_groups -->|"derives operations"| node_hall
node_canonical -->|"handles reduction flips"| node_ambiguity
node_crystal_user -->|"requests reindexing"| node_canonical
node_crystal_user -->|"provides stream data"| node_stream
node_stream -->|"supports trajectories"| node_manifold

click node_metric "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/metric.py"
click node_reduction "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/reduction.py"
click node_rootform "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/rootform.py"
click node_celldb "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/celldb.py"
click node_neartree "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/neartree.py"
click node_space_groups "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/space_groups.py"
click node_setting "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/setting.py"
click node_hall "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/hall.py"
click node_reflections "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/reflections.py"
click node_asu "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/asu.py"
click node_diagrams "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/diagrams.py"
click node_ambiguity "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/ambiguity.py"
click node_canonical "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/canonical.py"
click node_reindex "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/reindex.py"
click node_manifold "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/manifold.py"
click node_stream "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/crystfel_stream.py"
click node_pdb_app "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/pdb_app.py"
click node_handlers "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/serve/handlers.py"
click node_http_app "https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/serve/app.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_metric,node_reduction,node_rootform,node_celldb,node_neartree,node_crystal_user toneBlue
class node_space_groups,node_setting,node_hall,node_reflections,node_asu,node_diagrams toneAmber
class node_ambiguity,node_canonical,node_reindex,node_manifold,node_stream toneMint
class node_pdb_app,node_handlers,node_http_app toneRose
```

## Components

### Cell comparison

- [Cell metrics](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/metric.py): `agentsg/src/agentsg/cell/metric.py`
- [Niggli reduction](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/reduction.py): `agentsg/src/agentsg/cell/reduction.py`
- [Root invariants](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/rootform.py): `agentsg/src/agentsg/cell/rootform.py`
- [Cell database](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/celldb.py): `agentsg/src/agentsg/cell/celldb.py`
- [Metric index](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/neartree.py): `agentsg/src/agentsg/cell/neartree.py`

### Space-group symmetry

- [Space groups](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/space_groups.py): `agentsg/src/agentsg/space_groups.py`
- [Group settings](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/setting.py): `agentsg/src/agentsg/setting.py`
- [Hall operations](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/hall.py): `agentsg/src/agentsg/hall.py`
- [Reflection conditions](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/reflections.py): `agentsg/src/agentsg/reflections.py`
- [Asymmetric units](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/asu.py): `agentsg/src/agentsg/asu.py`
- [ITA diagrams](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/diagrams.py): `agentsg/src/agentsg/cell/diagrams.py`

### Serial reindexing

- [Reindexing ambiguity](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/ambiguity.py): `agentsg/src/agentsg/cell/ambiguity.py`
- [Canonical operators](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/canonical.py): `agentsg/src/agentsg/cell/canonical.py`
- [Reindexing](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/reindex.py): `agentsg/src/agentsg/cell/reindex.py`
- [Cell manifold](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/manifold.py): `agentsg/src/agentsg/cell/manifold.py`
- [CrystFEL streams](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/crystfel_stream.py): `agentsg/src/agentsg/cell/crystfel_stream.py`

### Data and interface

- [PDB database app](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/cell/pdb_app.py): `agentsg/src/agentsg/cell/pdb_app.py`
- [API handlers](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/serve/handlers.py): `agentsg/src/agentsg/serve/handlers.py`
- [HTTP service](https://github.com/phzwart/agentsg/blob/main/agentsg/src/agentsg/serve/app.py): `agentsg/src/agentsg/serve/app.py`

### Other components

- **Crystallography user**

## Connections

- Crystallography user → HTTP service: sends requests
- HTTP service → API handlers: dispatches requests
- API handlers → Space groups: resolves groups
- API handlers → Group settings: parses settings
- API handlers → Reflection conditions: computes conditions
- API handlers → Asymmetric units: uses reciprocal ASU
- API handlers → ITA diagrams: renders plates
- API handlers → Cell metrics: builds cell metrics
- API handlers → Niggli reduction: reduces cells
- API handlers → Root invariants: compares roots
- API handlers → Cell database: looks up cells
- HTTP service → Cell database: opens database
- Cell database → Metric index: builds index
- PDB database app → Cell database: builds database
- Space groups → Hall operations: derives operations
- Canonical operators → Reindexing ambiguity: handles reduction flips
- Crystallography user → Canonical operators: requests reindexing
- Crystallography user → CrystFEL streams: provides stream data
- CrystFEL streams → Cell manifold: supports trajectories