# schwarzschlyle/immune architecture

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

- Interactive diagram: https://gitdiagram.com/schwarzschlyle/immune
- Repository: https://github.com/schwarzschlyle/immune

## Overview

Immune is a runtime defense layer for LLM applications. An application initializes or protects SDK traffic; interception routes provider requests through codecs into the screening pipeline, which classifies conversation channels, finds reflex candidates, gathers sensor judgments, applies calibrated threat policy, and returns screened provider results with a verdict. Sessions preserve taint and provenance, while configuration and vaccines tune policy and detectors; telemetry reports outcomes. The README documents broad provider/framework compatibility and streaming. Several implementation paths are unsampled, so those capabilities are retained as subsystems without speculative call edges.

Main entry points: [`src/immune/core/pipeline.py`](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/pipeline.py) (Screening Pipeline), [`src/immune/intercept`](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/intercept) (Provider Interception), [`src/immune/api.py`](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/api.py) (Immune API), [`src/immune/cli`](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/cli) (CLI Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Setup and Interception"]
  node_api["Immune API<br/>[api.py]"]
  node_intercept["Provider Interception"]
  node_codecs["Provider Codecs"]
end

subgraph group_screening["Call Screening"]
  node_pipeline["Screening Pipeline<br/>[pipeline.py]"]
  node_conversation["Conversation Channels<br/>[conversation.py]"]
  node_reflexes["Reflex Detection"]
  node_candidates["Threat Candidates<br/>[candidates.py]"]
  node_sensor["Jev Sensor"]
  node_signals["Typed Signals<br/>[signals.py]"]
  node_assessment["Threat Assessment<br/>[assess.py]"]
  node_heads["Calibrated Heads"]
  node_decision["Policy Decisions<br/>[decide.py]"]
end

subgraph group_memory["Policy and Memory"]
  node_vaccines["Vaccine Rules"]
  node_config["Configuration"]
  node_sessions["Session Provenance"]
  node_state[("State Backends")]
end

subgraph group_operations["Management and Observability"]
  node_verdict["Verdict API<br/>[verdicts.py]"]
  node_telemetry["Telemetry"]
  node_cli["CLI Management"]
end

node_app(("LLM Application"))
node_providers(("Model Providers"))

node_app -->|"initializes"| node_api
node_app -->|"sends model calls"| node_intercept
node_api -->|"installs hooks"| node_intercept
node_intercept -.->|"dispatches calls"| node_pipeline
node_intercept -->|"routes formats"| node_codecs
node_codecs -->|"decodes messages"| node_conversation
node_pipeline -->|"screens representation"| node_conversation
node_pipeline -->|"finds findings"| node_reflexes
node_pipeline -->|"builds candidates"| node_candidates
node_pipeline -.->|"requests readings"| node_sensor
node_sensor -->|"returns signals"| node_signals
node_pipeline -->|"assesses threats"| node_assessment
node_pipeline -.->|"scores threats"| node_heads
node_pipeline -->|"decides actions"| node_decision
node_config -.->|"configures screening"| node_pipeline
node_vaccines -.->|"supplies detectors"| node_reflexes
node_pipeline -->|"updates provenance"| node_sessions
node_sessions -.->|"persists state"| node_state
node_decision -.->|"returns action"| node_pipeline
node_pipeline -.->|"returns screened result"| node_intercept
node_intercept -->|"forwards request"| node_providers
node_providers -->|"returns reply"| node_intercept
node_api -->|"exposes verdict"| node_verdict
node_pipeline -->|"emits observations"| node_telemetry
node_app -->|"reads outcome"| node_verdict
node_cli -->|"manages rules"| node_vaccines
node_cli -->|"loads settings"| node_config

click node_api "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/api.py"
click node_intercept "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/intercept"
click node_codecs "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/codecs"
click node_pipeline "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/pipeline.py"
click node_conversation "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/conversation.py"
click node_reflexes "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/reflexes"
click node_candidates "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/candidates.py"
click node_sensor "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/sensing"
click node_signals "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/sensing/signals.py"
click node_assessment "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/assess.py"
click node_heads "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/heads"
click node_decision "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/decide.py"
click node_vaccines "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/vaccines"
click node_config "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/config"
click node_sessions "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/sessions"
click node_state "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/state"
click node_verdict "https://github.com/schwarzschlyle/immune/blob/dev/src/immune/telemetry/verdicts.py"
click node_telemetry "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/telemetry"
click node_cli "https://github.com/schwarzschlyle/immune/tree/dev/src/immune/cli"

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_intercept,node_codecs toneBlue
class node_pipeline,node_conversation,node_reflexes,node_candidates,node_sensor,node_signals,node_assessment,node_heads,node_decision toneAmber
class node_vaccines,node_config,node_sessions,node_state toneMint
class node_verdict,node_telemetry,node_cli toneRose
class node_app,node_providers toneIndigo
```

## Components

### Setup and Interception

- [Immune API](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/api.py): `src/immune/api.py`
- [Provider Interception](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/intercept): `src/immune/intercept`
- [Provider Codecs](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/codecs): `src/immune/codecs`

### Call Screening

- [Screening Pipeline](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/pipeline.py): `src/immune/core/pipeline.py`
- [Conversation Channels](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/conversation.py): `src/immune/core/conversation.py`
- [Reflex Detection](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/reflexes): `src/immune/reflexes`
- [Threat Candidates](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/candidates.py): `src/immune/core/candidates.py`
- [Jev Sensor](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/sensing): `src/immune/sensing`
- [Typed Signals](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/sensing/signals.py): `src/immune/sensing/signals.py`
- [Threat Assessment](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/assess.py): `src/immune/core/assess.py`
- [Calibrated Heads](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/heads): `src/immune/heads`
- [Policy Decisions](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/core/decide.py): `src/immune/core/decide.py`

### Policy and Memory

- [Vaccine Rules](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/vaccines): `src/immune/vaccines`
- [Configuration](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/config): `src/immune/config`
- [Session Provenance](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/sessions): `src/immune/sessions`
- [State Backends](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/state): `src/immune/state`

### Management and Observability

- [Verdict API](https://github.com/schwarzschlyle/immune/blob/dev/src/immune/telemetry/verdicts.py): `src/immune/telemetry/verdicts.py`
- [Telemetry](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/telemetry): `src/immune/telemetry`
- [CLI Management](https://github.com/schwarzschlyle/immune/tree/dev/src/immune/cli): `src/immune/cli`

### Other components

- **LLM Application**
- **Model Providers**

## Connections

- LLM Application → Immune API: initializes (evidence: `README.md`)
- LLM Application → Provider Interception: sends model calls (evidence: `README.md`)
- Immune API → Provider Interception: installs hooks (evidence: `src/immune/api.py`)
- Provider Interception → Screening Pipeline: dispatches calls
- Provider Interception → Provider Codecs: routes formats (evidence: `src/immune/intercept/router.py`)
- Provider Codecs → Conversation Channels: decodes messages (evidence: `src/immune/codecs/base.py`)
- Screening Pipeline → Conversation Channels: screens representation (evidence: `src/immune/core/pipeline.py`)
- Screening Pipeline → Reflex Detection: finds findings (evidence: `src/immune/core/pipeline.py`)
- Screening Pipeline → Threat Candidates: builds candidates (evidence: `src/immune/core/pipeline.py`)
- Screening Pipeline → Jev Sensor: requests readings (evidence: `src/immune/core/pipeline.py`)
- Jev Sensor → Typed Signals: returns signals (evidence: `src/immune/sensing/sensor.py`)
- Screening Pipeline → Threat Assessment: assesses threats (evidence: `src/immune/core/pipeline.py`)
- Screening Pipeline → Calibrated Heads: scores threats
- Screening Pipeline → Policy Decisions: decides actions (evidence: `src/immune/core/pipeline.py`)
- Configuration → Screening Pipeline: configures screening (evidence: `src/immune/core/pipeline.py`)
- Vaccine Rules → Reflex Detection: supplies detectors
- Screening Pipeline → Session Provenance: updates provenance (evidence: `src/immune/core/pipeline.py`)
- Session Provenance → State Backends: persists state
- Policy Decisions → Screening Pipeline: returns action (evidence: `src/immune/core/pipeline.py`)
- Screening Pipeline → Provider Interception: returns screened result
- Provider Interception → Model Providers: forwards request (evidence: `README.md`)
- Model Providers → Provider Interception: returns reply (evidence: `README.md`)
- Immune API → Verdict API: exposes verdict (evidence: `src/immune/api.py`)
- Screening Pipeline → Telemetry: emits observations (evidence: `src/immune/core/pipeline.py`)
- LLM Application → Verdict API: reads outcome (evidence: `README.md`)
- CLI Management → Vaccine Rules: manages rules (evidence: `src/immune/cli/commands/vaccines.py`)
- CLI Management → Configuration: loads settings (evidence: `src/immune/cli/commands/vaccines.py`)
