# siddharth-1118/vss-self-deciding-agent architecture

> Architecture diagram of the GitHub repository siddharth-1118/vss-self-deciding-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddharth-1118/vss-self-deciding-agent
- Repository: https://github.com/siddharth-1118/vss-self-deciding-agent

## Overview

VSS accepts text or JSON state plus typed questions, validates the request, and produces schema-constrained answers with probabilities, confidence, and optional abstention in a shared model pass. Its other major branches cover training and data preparation, calibration and evaluation, and REST serving. Some relationships are documented only by the README or SOURCE INDEX; unsampled modules are included where their role is established, without inferring internal calls.

Main entry points: [`src/vss/model/vss_model.py`](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/vss_model.py) (VSS model), [`src/vss/api.py`](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/api.py) (Public API), [`src/vss/data/schema.py`](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/schema.py) (Training data schema), [`src/vss/training/trainer.py`](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/trainer.py) (Trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["API and serving"]
  node_api["Public API<br/>[api.py]"]
  node_server["REST server<br/>[server.py]"]
end

subgraph group_inference["Inference pipeline"]
  node_request_schema["Request validation<br/>[schema.py]"]
  node_batching["Batching<br/>[batching.py]"]
  node_engine["Answer construction<br/>[engine.py]"]
end

subgraph group_model["Model internals"]
  node_model_core["VSS model<br/>[vss_model.py]"]
  node_encoder["State encoder<br/>[encoder.py]"]
  node_transformer["Transformer<br/>[transformer.py]"]
  node_serialization["State serialization<br/>[serialize.py]"]
  node_tokenizer["Tokenizer<br/>[tokenizer.py]"]
  node_bpe_tokenizer["BPE tokenizer<br/>[tokenizer_bpe.py]"]
  node_question_heads["Typed question heads<br/>[questions.py]"]
  node_config["Model configuration<br/>[config.py]"]
end

subgraph group_data["Data and training"]
  node_dataset_schema["Training data schema<br/>[schema.py]"]
  node_synthetic["Synthetic generator<br/>[synthetic.py]"]
  node_banking["Banking77 loader<br/>[banking77.py]"]
  node_clinc["CLINC150 loader<br/>[clinc150.py]"]
  node_trainer["Trainer<br/>[trainer.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_curriculum["Curriculum<br/>[curriculum.py]"]
  node_rlcd["RLCD training<br/>[rlcd.py]"]
  node_selection["Checkpoint selection<br/>[selection.py]"]
end

subgraph group_quality["Calibration and evaluation"]
  node_calibration["Calibration<br/>[calibration.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
end

node_user(("Decision caller"))
node_rest_client(("REST client"))

node_user -->|"submits decisions"| node_api
node_rest_client -->|"posts requests"| node_server
node_server -->|"delegates to"| node_api
node_api -->|"validates requests"| node_request_schema
node_api -->|"runs batches"| node_batching
node_api -->|"runs single decisions"| node_engine
node_batching -->|"runs forward pass"| node_model_core
node_batching -->|"builds answers"| node_engine
node_batching -->|"parses questions"| node_question_heads
node_engine -->|"formats model outputs"| node_model_core
node_model_core -->|"encodes state"| node_encoder
node_model_core -->|"routes questions"| node_question_heads
node_model_core -->|"uses settings"| node_config
node_encoder -->|"serializes state"| node_serialization
node_encoder -->|"tokenizes text"| node_tokenizer
node_encoder -->|"encodes tokens"| node_transformer
node_model_core -->|"loads vocabulary"| node_tokenizer
node_synthetic -->|"validates examples"| node_dataset_schema
node_banking -->|"uses data schema"| node_dataset_schema
node_clinc -->|"uses data schema"| node_dataset_schema
node_trainer -->|"trains model"| node_model_core
node_trainer -->|"consumes examples"| node_dataset_schema
node_trainer -->|"computes loss"| node_losses
node_trainer -->|"selects checkpoints"| node_selection
node_curriculum -->|"generates stages"| node_synthetic
node_curriculum -->|"uses examples"| node_dataset_schema
node_rlcd -->|"trains model"| node_model_core
node_rlcd -->|"uses losses"| node_losses
node_api -.->|"reports confidence"| node_calibration
node_calibration -->|"complements confidence head"| node_question_heads
node_metrics -.->|"measures calibration"| node_calibration

click node_api "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/api.py"
click node_server "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/server.py"
click node_request_schema "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/schema.py"
click node_batching "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/batching.py"
click node_engine "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/engine.py"
click node_model_core "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/vss_model.py"
click node_encoder "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/encoder.py"
click node_transformer "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/transformer.py"
click node_serialization "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/serialize.py"
click node_tokenizer "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/tokenizer.py"
click node_bpe_tokenizer "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/tokenizer_bpe.py"
click node_question_heads "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/questions.py"
click node_config "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/config.py"
click node_dataset_schema "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/schema.py"
click node_synthetic "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/synthetic.py"
click node_banking "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/banking77.py"
click node_clinc "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/clinc150.py"
click node_trainer "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/trainer.py"
click node_losses "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/losses.py"
click node_curriculum "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/curriculum.py"
click node_rlcd "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/rlcd.py"
click node_selection "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/selection.py"
click node_calibration "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/calibration.py"
click node_metrics "https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/eval/metrics.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_server,node_rest_client toneBlue
class node_request_schema,node_batching,node_engine toneAmber
class node_model_core,node_encoder,node_transformer,node_serialization,node_tokenizer,node_bpe_tokenizer,node_question_heads,node_config toneMint
class node_dataset_schema,node_synthetic,node_banking,node_clinc,node_trainer,node_losses,node_curriculum,node_rlcd,node_selection toneRose
class node_calibration,node_metrics,node_user toneIndigo
```

## Components

### API and serving

- [Public API](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/api.py): `src/vss/api.py`
- [REST server](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/server.py): `src/vss/inference/server.py`

### Inference pipeline

- [Request validation](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/schema.py): `src/vss/inference/schema.py`
- [Batching](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/batching.py): `src/vss/inference/batching.py`
- [Answer construction](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/inference/engine.py): `src/vss/inference/engine.py`

### Model internals

- [VSS model](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/vss_model.py): `src/vss/model/vss_model.py`
- [State encoder](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/encoder.py): `src/vss/model/encoder.py`
- [Transformer](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/transformer.py): `src/vss/model/transformer.py`
- [State serialization](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/serialize.py): `src/vss/model/serialize.py`
- [Tokenizer](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/tokenizer.py): `src/vss/model/tokenizer.py`
- [BPE tokenizer](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/tokenizer_bpe.py): `src/vss/model/tokenizer_bpe.py`
- [Typed question heads](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/questions.py): `src/vss/model/questions.py`
- [Model configuration](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/config.py): `src/vss/model/config.py`

### Data and training

- [Training data schema](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/schema.py): `src/vss/data/schema.py`
- [Synthetic generator](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/synthetic.py): `src/vss/data/synthetic.py`
- [Banking77 loader](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/banking77.py): `src/vss/data/banking77.py`
- [CLINC150 loader](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/data/clinc150.py): `src/vss/data/clinc150.py`
- [Trainer](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/trainer.py): `src/vss/training/trainer.py`
- [Training losses](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/losses.py): `src/vss/training/losses.py`
- [Curriculum](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/curriculum.py): `src/vss/training/curriculum.py`
- [RLCD training](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/rlcd.py): `src/vss/training/rlcd.py`
- [Checkpoint selection](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/training/selection.py): `src/vss/training/selection.py`

### Calibration and evaluation

- [Calibration](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/model/calibration.py): `src/vss/model/calibration.py`
- [Evaluation metrics](https://github.com/siddharth-1118/vss-self-deciding-agent/blob/main/src/vss/eval/metrics.py): `src/vss/eval/metrics.py`

### Other components

- **Decision caller**
- **REST client**

## Connections

- Decision caller → Public API: submits decisions
- REST client → REST server: posts requests
- REST server → Public API: delegates to (evidence: `src/vss/inference/server.py`)
- Public API → Request validation: validates requests (evidence: `src/vss/api.py`)
- Public API → Batching: runs batches (evidence: `src/vss/api.py`)
- Public API → Answer construction: runs single decisions (evidence: `src/vss/api.py`)
- Batching → VSS model: runs forward pass (evidence: `src/vss/inference/batching.py`)
- Batching → Answer construction: builds answers (evidence: `src/vss/inference/batching.py`)
- Batching → Typed question heads: parses questions (evidence: `src/vss/inference/batching.py`)
- Answer construction → VSS model: formats model outputs (evidence: `src/vss/inference/engine.py`)
- VSS model → State encoder: encodes state (evidence: `src/vss/model/vss_model.py`)
- VSS model → Typed question heads: routes questions (evidence: `src/vss/model/vss_model.py`)
- VSS model → Model configuration: uses settings (evidence: `src/vss/model/vss_model.py`)
- State encoder → State serialization: serializes state (evidence: `src/vss/model/encoder.py`)
- State encoder → Tokenizer: tokenizes text (evidence: `src/vss/model/encoder.py`)
- State encoder → Transformer: encodes tokens (evidence: `src/vss/model/encoder.py`)
- VSS model → Tokenizer: loads vocabulary (evidence: `src/vss/model/vss_model.py`)
- Synthetic generator → Training data schema: validates examples (evidence: `src/vss/data/synthetic.py`)
- Banking77 loader → Training data schema: uses data schema (evidence: `src/vss/data/banking77.py`)
- CLINC150 loader → Training data schema: uses data schema (evidence: `src/vss/data/clinc150.py`)
- Trainer → VSS model: trains model (evidence: `src/vss/training/trainer.py`)
- Trainer → Training data schema: consumes examples (evidence: `src/vss/training/trainer.py`)
- Trainer → Training losses: computes loss (evidence: `src/vss/training/trainer.py`)
- Trainer → Checkpoint selection: selects checkpoints (evidence: `src/vss/training/trainer.py`)
- Curriculum → Synthetic generator: generates stages (evidence: `src/vss/training/curriculum.py`)
- Curriculum → Training data schema: uses examples (evidence: `src/vss/training/curriculum.py`)
- RLCD training → VSS model: trains model (evidence: `src/vss/training/rlcd.py`)
- RLCD training → Training losses: uses losses (evidence: `src/vss/training/rlcd.py`)
- Public API → Calibration: reports confidence
- Calibration → Typed question heads: complements confidence head (evidence: `src/vss/model/calibration.py`)
- Evaluation metrics → Calibration: measures calibration
