# afonsopereira1/agents-project architecture

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

- Interactive diagram: https://gitdiagram.com/afonsopereira1/agents-project
- Repository: https://github.com/afonsopereira1/agents-project

## Overview

ISIA simulates decentralized wildlife-threat monitoring: local sensors and human informants provide imperfect observations; incident agents corroborate evidence and apply response policy; mobile resources negotiate and execute verification or ranger missions. The simulation runner assembles agents, scenario/world state, and movement, while the evaluation collector measures runs and updates reputation from evaluator-side results. The README documents this end-to-end flow and capabilities; some connections below are supported only by the source index, so unsampled internals are not expanded beyond those references.

Main entry points: [`src/isia/simulation/runner.py`](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/runner.py) (Run orchestrator), [`src/isia/agents/incident.py`](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/incident.py) (Incident initiator), [`src/isia/agents/mobile.py`](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/mobile.py) (Mobile resources), [`src/isia/communication/messages.py`](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/communication/messages.py) (Protocol messages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Monitoring agents"]
  node_sensor["Sensor agents<br/>[sensor.py]"]
  node_informant["Human informants<br/>[informant.py]"]
  node_incident["Incident initiator<br/>[incident.py]"]
  node_mobile["Mobile resources<br/>[mobile.py]"]
  node_drone["Drone, ranger, vehicle<br/>[drone.py]"]
end

subgraph group_reasoning["Local reasoning"]
  node_corroboration["Evidence corroboration<br/>[corroboration.py]"]
  node_policy["Response policy<br/>[policy.py]"]
  node_allocation["Mission allocation<br/>[allocation.py]"]
  node_reputation["Source reputation<br/>[reputation.py]"]
end

subgraph group_coordination["Messaging and domain"]
  node_messages["Protocol messages<br/>[messages.py]"]
  node_transport["Message transport<br/>[transport.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_incident_state["Incident state<br/>[incident_state.py]"]
end

subgraph group_simulation["Simulation runtime"]
  node_runner["Run orchestrator<br/>[runner.py]"]
  node_scenario["Scenario and feeds<br/>[scenario.py]"]
  node_world["World state<br/>[world.py]"]
  node_movement["Movement<br/>[movement.py]"]
  node_clock["Simulation clock<br/>[clock.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_collector["Experiment collector<br/>[collector.py]"]
  node_metrics["Run metrics<br/>[metrics.py]"]
  node_calibration["Calibration<br/>[calibration.py]"]
end

node_operator(("Scenario operator"))

node_operator -->|"starts run"| node_runner
node_runner -->|"configures scenario"| node_scenario
node_runner -->|"configures world"| node_world
node_scenario -->|"uses world"| node_world
node_world -->|"uses clock"| node_clock
node_runner -->|"creates agents"| node_sensor
node_runner -->|"creates agents"| node_informant
node_runner -->|"creates initiators"| node_incident
node_runner -->|"creates resources"| node_mobile
node_drone -->|"specializes"| node_mobile
node_sensor -->|"evaluates evidence"| node_corroboration
node_informant -->|"supports evidence"| node_corroboration
node_incident -->|"corroborates reports"| node_corroboration
node_incident -->|"selects response"| node_policy
node_incident -->|"requests resources"| node_allocation
node_mobile -->|"evaluates bids"| node_allocation
node_mobile -->|"executes movement"| node_movement
node_incident -->|"tracks state"| node_incident_state
node_sensor -->|"sends requests"| node_messages
node_informant -->|"sends responses"| node_messages
node_mobile -->|"negotiates missions"| node_messages
node_transport -->|"transports"| node_messages
node_messages -->|"serializes models"| node_models
node_runner -->|"uses movement"| node_movement
node_runner -->|"runs episodes"| node_collector
node_collector -->|"calculates metrics"| node_metrics
node_collector -->|"updates reputation"| node_reputation
node_metrics -->|"uses task constants"| node_allocation
node_calibration -->|"validates domain values"| node_models

click node_runner "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/runner.py"
click node_scenario "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/scenario.py"
click node_world "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/world.py"
click node_movement "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/movement.py"
click node_clock "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/clock.py"
click node_sensor "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/sensor.py"
click node_informant "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/informant.py"
click node_incident "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/incident.py"
click node_mobile "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/mobile.py"
click node_drone "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/drone.py"
click node_corroboration "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/corroboration.py"
click node_policy "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/policy.py"
click node_allocation "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/allocation.py"
click node_reputation "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/reputation.py"
click node_messages "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/communication/messages.py"
click node_transport "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/communication/transport.py"
click node_models "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/domain/models.py"
click node_incident_state "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/domain/incident_state.py"
click node_collector "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/evaluation/collector.py"
click node_metrics "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/evaluation/metrics.py"
click node_calibration "https://github.com/afonsopereira1/agents-project/blob/main/src/isia/evaluation/calibration.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_sensor,node_informant,node_incident,node_mobile,node_drone toneBlue
class node_corroboration,node_policy,node_allocation,node_reputation toneAmber
class node_messages,node_transport,node_models,node_incident_state toneMint
class node_runner,node_scenario,node_world,node_movement,node_clock toneRose
class node_collector,node_metrics,node_calibration,node_operator toneIndigo
```

## Components

### Monitoring agents

- [Sensor agents](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/sensor.py): `src/isia/agents/sensor.py`
- [Human informants](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/informant.py): `src/isia/agents/informant.py`
- [Incident initiator](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/incident.py): `src/isia/agents/incident.py`
- [Mobile resources](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/mobile.py): `src/isia/agents/mobile.py`
- [Drone, ranger, vehicle](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/agents/drone.py): `src/isia/agents/drone.py`

### Local reasoning

- [Evidence corroboration](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/corroboration.py): `src/isia/reasoning/corroboration.py`
- [Response policy](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/policy.py): `src/isia/reasoning/policy.py`
- [Mission allocation](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/allocation.py): `src/isia/reasoning/allocation.py`
- [Source reputation](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/reasoning/reputation.py): `src/isia/reasoning/reputation.py`

### Messaging and domain

- [Protocol messages](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/communication/messages.py): `src/isia/communication/messages.py`
- [Message transport](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/communication/transport.py): `src/isia/communication/transport.py`
- [Domain models](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/domain/models.py): `src/isia/domain/models.py`
- [Incident state](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/domain/incident_state.py): `src/isia/domain/incident_state.py`

### Simulation runtime

- [Run orchestrator](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/runner.py): `src/isia/simulation/runner.py`
- [Scenario and feeds](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/scenario.py): `src/isia/simulation/scenario.py`
- [World state](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/world.py): `src/isia/simulation/world.py`
- [Movement](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/movement.py): `src/isia/simulation/movement.py`
- [Simulation clock](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/simulation/clock.py): `src/isia/simulation/clock.py`

### Evaluation

- [Experiment collector](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/evaluation/collector.py): `src/isia/evaluation/collector.py`
- [Run metrics](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/evaluation/metrics.py): `src/isia/evaluation/metrics.py`
- [Calibration](https://github.com/afonsopereira1/agents-project/blob/main/src/isia/evaluation/calibration.py): `src/isia/evaluation/calibration.py`

### Other components

- **Scenario operator**

## Connections

- Scenario operator → Run orchestrator: starts run (evidence: `README.md`)
- Run orchestrator → Scenario and feeds: configures scenario (evidence: `src/isia/simulation/runner.py`)
- Run orchestrator → World state: configures world (evidence: `src/isia/simulation/runner.py`)
- Scenario and feeds → World state: uses world (evidence: `src/isia/simulation/scenario.py`)
- World state → Simulation clock: uses clock (evidence: `src/isia/simulation/world.py`)
- Run orchestrator → Sensor agents: creates agents (evidence: `src/isia/simulation/runner.py`)
- Run orchestrator → Human informants: creates agents (evidence: `src/isia/simulation/runner.py`)
- Run orchestrator → Incident initiator: creates initiators (evidence: `src/isia/simulation/runner.py`)
- Run orchestrator → Mobile resources: creates resources (evidence: `src/isia/simulation/runner.py`)
- Drone, ranger, vehicle → Mobile resources: specializes (evidence: `src/isia/agents/drone.py`)
- Sensor agents → Evidence corroboration: evaluates evidence (evidence: `src/isia/agents/sensor.py`)
- Human informants → Evidence corroboration: supports evidence (evidence: `src/isia/agents/informant.py`)
- Incident initiator → Evidence corroboration: corroborates reports (evidence: `src/isia/agents/incident.py`)
- Incident initiator → Response policy: selects response (evidence: `src/isia/agents/incident.py`)
- Incident initiator → Mission allocation: requests resources (evidence: `src/isia/agents/incident.py`)
- Mobile resources → Mission allocation: evaluates bids (evidence: `src/isia/agents/mobile.py`)
- Mobile resources → Movement: executes movement (evidence: `src/isia/agents/mobile.py`)
- Incident initiator → Incident state: tracks state (evidence: `src/isia/agents/incident.py`)
- Sensor agents → Protocol messages: sends requests (evidence: `src/isia/agents/sensor.py`)
- Human informants → Protocol messages: sends responses (evidence: `src/isia/agents/informant.py`)
- Mobile resources → Protocol messages: negotiates missions (evidence: `src/isia/agents/mobile.py`)
- Message transport → Protocol messages: transports (evidence: `src/isia/communication/transport.py`)
- Protocol messages → Domain models: serializes models (evidence: `src/isia/communication/messages.py`)
- Run orchestrator → Movement: uses movement (evidence: `src/isia/simulation/runner.py`)
- Run orchestrator → Experiment collector: runs episodes (evidence: `src/isia/evaluation/collector.py`)
- Experiment collector → Run metrics: calculates metrics (evidence: `src/isia/evaluation/collector.py`)
- Experiment collector → Source reputation: updates reputation (evidence: `src/isia/evaluation/collector.py`)
- Run metrics → Mission allocation: uses task constants (evidence: `src/isia/evaluation/metrics.py`)
- Calibration → Domain models: validates domain values (evidence: `src/isia/evaluation/calibration.py`)
