# kaimnancy/gauri-livestock-assistant architecture

> Architecture diagram of the GitHub repository kaimnancy/gauri-livestock-assistant, 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/kaimnancy/gauri-livestock-assistant
- Repository: https://github.com/kaimnancy/gauri-livestock-assistant

## Overview

Gauri is a livestock record-keeping and triage assistant. A caregiver submits an English description and optional photo; the orchestrator applies deterministic safety checks, routes the task, and manages animal context and clarification. Record tasks use agent tools and file-backed JSON/Markdown profiles; other documented routes include triage, visual health checks, and general queries. Phase 2 agents and regional-language replies are represented by stubs. Relationships are based on README claims and shown source references; where the live record-agent wiring is unclear, the edge is marked unverified.

Main entry points: [`Gauri/gauri_app/orchestrator/agent.py`](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/agent.py) (Task Orchestrator), [`Gauri/gauri_app/record/record_agent.py`](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/record/record_agent.py) (Record Agent), [`Gauri/gauri_app/tools/record_tools.py`](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/tools/record_tools.py) (Record Tools), [`Gauri/gauri_app/core/schemas.py`](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/schemas.py) (Payload and Response Schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Input and Coordination"]
  node_orchestrator["Task Orchestrator<br/>[agent.py]"]
  node_router["Intent Router<br/>[agent.py]"]
  node_session["Session and Roster State<br/>[state_keys.py]"]
end

subgraph group_safety["Safety"]
  node_safety_gate["Safety Gate<br/>[safety.py]"]
end

subgraph group_agents["Agent Capabilities"]
  node_record_agent["Record Agent<br/>[record_agent.py]"]
  node_triage["Triage Handler<br/>[stubs.py]"]
  node_health_check["Visual Health Check<br/>[stubs.py]"]
  node_general_query["General Query Handler<br/>[stubs.py]"]
  node_behaviour_reply["Reply Formatter<br/>[stubs.py]"]
end

subgraph group_records["Animal Records"]
  node_record_tools["Record Tools<br/>[record_tools.py]"]
  node_doc_store[("Animal Document Store<br/>[doc_store.py]")]
end

subgraph group_contracts["Shared Contracts"]
  node_schemas["Payload and Response Schemas<br/>[schemas.py]"]
  node_models["Model Factory<br/>[models.py]"]
end

node_caregiver(("Caregiver"))
node_vet(("Vet / 1962"))
node_ollama(("Ollama Model Service"))

node_caregiver -->|"submits request"| node_orchestrator
node_orchestrator -->|"checks input"| node_safety_gate
node_orchestrator -->|"classifies request"| node_router
node_orchestrator -->|"updates state"| node_session
node_safety_gate -->|"escalates emergencies"| node_vet
node_orchestrator -->|"dispatches triage"| node_triage
node_orchestrator -->|"dispatches visual check"| node_health_check
node_orchestrator -->|"dispatches query"| node_general_query
node_orchestrator -.->|"may dispatch record task"| node_record_agent
node_orchestrator -->|"uses roster tools"| node_record_tools
node_record_agent -->|"invokes tools"| node_record_tools
node_record_tools -->|"reads and writes"| node_doc_store
node_orchestrator -->|"formats response"| node_behaviour_reply
node_triage -->|"returns agent response"| node_schemas
node_health_check -->|"returns agent response"| node_schemas
node_record_agent -->|"uses task contracts"| node_schemas
node_record_agent -->|"gets model"| node_models
node_models -->|"configures local model"| node_ollama

click node_orchestrator "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/agent.py"
click node_router "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/agent.py"
click node_session "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/state_keys.py"
click node_safety_gate "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/safety.py"
click node_record_agent "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/record/record_agent.py"
click node_triage "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py"
click node_health_check "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py"
click node_general_query "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py"
click node_behaviour_reply "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py"
click node_record_tools "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/tools/record_tools.py"
click node_doc_store "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/doc_store.py"
click node_schemas "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/schemas.py"
click node_models "https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/models.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_orchestrator,node_router,node_session toneBlue
class node_safety_gate toneAmber
class node_record_agent,node_triage,node_health_check,node_general_query,node_behaviour_reply toneMint
class node_record_tools,node_doc_store toneRose
class node_schemas,node_models,node_caregiver,node_vet,node_ollama toneIndigo
```

## Components

### Input and Coordination

- [Task Orchestrator](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/agent.py): `Gauri/gauri_app/orchestrator/agent.py`
- [Intent Router](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/agent.py): `Gauri/gauri_app/orchestrator/agent.py`
- [Session and Roster State](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/state_keys.py): `Gauri/gauri_app/core/state_keys.py`

### Safety

- [Safety Gate](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/safety.py): `Gauri/gauri_app/core/safety.py`

### Agent Capabilities

- [Record Agent](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/record/record_agent.py): `Gauri/gauri_app/record/record_agent.py`
- [Triage Handler](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py): `Gauri/gauri_app/orchestrator/stubs.py`
- [Visual Health Check](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py): `Gauri/gauri_app/orchestrator/stubs.py`
- [General Query Handler](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py): `Gauri/gauri_app/orchestrator/stubs.py`
- [Reply Formatter](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/orchestrator/stubs.py): `Gauri/gauri_app/orchestrator/stubs.py`

### Animal Records

- [Record Tools](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/tools/record_tools.py): `Gauri/gauri_app/tools/record_tools.py`
- [Animal Document Store](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/doc_store.py): `Gauri/gauri_app/core/doc_store.py`

### Shared Contracts

- [Payload and Response Schemas](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/schemas.py): `Gauri/gauri_app/core/schemas.py`
- [Model Factory](https://github.com/kaimnancy/gauri-livestock-assistant/blob/main/Gauri/gauri_app/core/models.py): `Gauri/gauri_app/core/models.py`

### Other components

- **Caregiver**
- **Vet / 1962**
- **Ollama Model Service**

## Connections

- Caregiver → Task Orchestrator: submits request (evidence: `README.md`)
- Task Orchestrator → Safety Gate: checks input (evidence: `Gauri/gauri_app/orchestrator/agent.py`)
- Task Orchestrator → Intent Router: classifies request (evidence: `Gauri/gauri_app/orchestrator/agent.py`)
- Task Orchestrator → Session and Roster State: updates state (evidence: `Gauri/gauri_app/orchestrator/agent.py`)
- Safety Gate → Vet / 1962: escalates emergencies (evidence: `README.md`)
- Task Orchestrator → Triage Handler: dispatches triage (evidence: `README.md`)
- Task Orchestrator → Visual Health Check: dispatches visual check (evidence: `README.md`)
- Task Orchestrator → General Query Handler: dispatches query (evidence: `README.md`)
- Task Orchestrator → Record Agent: may dispatch record task
- Task Orchestrator → Record Tools: uses roster tools (evidence: `Gauri/gauri_app/orchestrator/agent.py`)
- Record Agent → Record Tools: invokes tools (evidence: `Gauri/gauri_app/record/record_agent.py`)
- Record Tools → Animal Document Store: reads and writes (evidence: `Gauri/gauri_app/tools/record_tools.py`)
- Task Orchestrator → Reply Formatter: formats response (evidence: `Gauri/gauri_app/orchestrator/agent.py`)
- Triage Handler → Payload and Response Schemas: returns agent response (evidence: `Gauri/gauri_app/orchestrator/stubs.py`)
- Visual Health Check → Payload and Response Schemas: returns agent response (evidence: `Gauri/gauri_app/orchestrator/stubs.py`)
- Record Agent → Payload and Response Schemas: uses task contracts (evidence: `Gauri/gauri_app/record/record_agent.py`)
- Record Agent → Model Factory: gets model (evidence: `Gauri/gauri_app/record/record_agent.py`)
- Model Factory → Ollama Model Service: configures local model (evidence: `Gauri/gauri_app/core/models.py`)
