# octopus237/agentic-ai architecture

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

- Interactive diagram: https://gitdiagram.com/octopus237/agentic-ai
- Repository: https://github.com/octopus237/agentic-ai

## Overview

#### Purpose and Entry Point

This is a local, LLM-driven Wazuh security investigation service. An analyst submits a natural-language question; an Ollama-hosted model selects Wazuh data tools, iterates on evidence, and returns a verdict with an auditable tool-call trail.

The executable entry point is `app.py`, which provides Flask UI/API hosting and lifecycle commands (`start`, `stop`, `status`, `restart`, `run`).

Paths: `app.py`, `README.md`

#### Application and Process Host

`app.py` owns the Flask web interface, request handling, live investigation control, cancellation, report presentation, auto-run scheduling, and background process management. It binds according to `UI_HOST` and `UI_PORT`, and its managed background mode writes PID/log artifacts.

This is the orchestration boundary between browser-facing interaction and the agent runtime.

Paths: `app.py`

#### Agentic Investigation Runtime

`agent_tools.py` implements the investigation loop. It sends the analyst prompt and tool definitions to Ollama, receives model-selected tool calls, executes them, feeds observations back into the conversation, and repeats until the model produces a final answer or reaches `AGENTIC_MAX_STEPS`.

The model is responsible for investigative planning and convergence; the application enforces the tool-call budget and can stop an active run.

Paths: `agent_tools.py`

#### Tool Boundary and Audit Trail

The agent exposes constrained investigation tools rather than direct model access to Wazuh. Tool results become subsequent model context, while each invoked query/call is recorded as an audit trail. Completed runs persist a verdict plus this trail; history is JSON-backed and capped at 50 reports.

This boundary is important for traceability: the LLM plans, but repository code performs external data access.

Paths: `agent_tools.py`, `app.py`

#### Wazuh Data Access Layer

`client.py` isolates external Wazuh communication from agent reasoning. It accesses two distinct services:

- Wazuh Indexer API on port 9200, using basic authentication, for alerts, aggregations, and event timelines.
- Wazuh Server API on port 55000, using token authentication, for live host inventory.

The design assumes one reachable Wazuh manager and one indexer. Credentials, endpoint URLs, and TLS behavior come from environment configuration.

Paths: `client.py`, `agent_tools.py`

#### Primary Control and Data Flow

1. Browser submits a question or scheduled triage begins in `app.py`.
2. `app.py` starts an agent run and streams progress, reasoning/tool activity, and final output to the UI.
3. `agent_tools.py` calls the configured Ollama model and processes requested tools.
4. Tool implementations call `client.py`.
5. `client.py` queries Wazuh Indexer and/or Server APIs and returns normalized results to the agent loop.
6. The final verdict and full audit trail are saved and made available in the Reports UI.

Paths: `app.py`, `agent_tools.py`, `client.py`

#### Runtime Dependencies and Infrastructure

The service requires Python 3.10+, Flask/CORS for the local UI, `requests` for Wazuh HTTP access, and the Ollama Python client. Ollama may be local or network-hosted and must provide a capable tool-calling model. Wazuh manager, indexer, and Ollama are external network dependencies configured through `.env`.

Paths: `app.py`, `agent_tools.py`, `client.py`

Main entry points: [`agent_tools.py`](https://github.com/octopus237/agentic-ai/blob/main/agent_tools.py) (Investigation Loop), [`app.py`](https://github.com/octopus237/agentic-ai/blob/main/app.py) (Flask Host & Orchestrator), [`client.py`](https://github.com/octopus237/agentic-ai/blob/main/client.py) (Wazuh Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local_service["Local Investigation Service"]
  node_app["Flask Host &amp; Orchestrator<br/>Flask application<br/>[app.py]"]
  node_scheduler["Auto-run Scheduler<br/>scheduled triage<br/>[app.py]"]
  node_agent["Investigation Loop<br/>agent runtime<br/>[agent_tools.py]"]
  node_tools{{"Constrained Tools<br/>tool boundary<br/>[agent_tools.py]"}}
  node_audit["Reports &amp; Audit History<br/>JSON-backed history<br/>[app.py]"]
  node_wazuh_client["Wazuh Client<br/>data access layer<br/>[client.py]"]
end

subgraph group_external["External Services"]
  node_ollama{{"Ollama Model<br/>LLM service"}}
  node_indexer[("Wazuh Indexer API<br/>external API :9200")]
  node_server[("Wazuh Server API<br/>external API :55000")]
end

node_browser["Analyst Browser<br/>user interface"]
node_environment["Environment Configuration<br/>runtime configuration"]

node_browser -->|"questions / UI requests"| node_app
node_app -->|"progress and reports"| node_browser
node_scheduler -->|"starts triage"| node_app
node_app -->|"starts / cancels run"| node_agent
node_agent -->|"prompt and tool definitions"| node_ollama
node_ollama -->|"tool calls / final answer"| node_agent
node_agent -->|"executes requested tools"| node_tools
node_tools -->|"query operations"| node_wazuh_client
node_wazuh_client -->|"basic-auth queries"| node_indexer
node_wazuh_client -->|"token-auth inventory"| node_server
node_tools -->|"observations and audit calls"| node_agent
node_agent -->|"verdict and tool trail"| node_audit
node_app -->|"presents saved reports"| node_audit
node_environment -.->|"UI host / port"| node_app
node_environment -.->|"model settings"| node_agent
node_environment -.->|"endpoints and credentials"| node_wazuh_client

click node_app "https://github.com/octopus237/agentic-ai/blob/main/app.py"
click node_scheduler "https://github.com/octopus237/agentic-ai/blob/main/app.py"
click node_agent "https://github.com/octopus237/agentic-ai/blob/main/agent_tools.py"
click node_tools "https://github.com/octopus237/agentic-ai/blob/main/agent_tools.py"
click node_audit "https://github.com/octopus237/agentic-ai/blob/main/app.py"
click node_wazuh_client "https://github.com/octopus237/agentic-ai/blob/main/client.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_app,node_scheduler,node_agent,node_tools,node_audit,node_wazuh_client toneBlue
class node_ollama,node_indexer,node_server toneAmber
class node_browser,node_environment toneNeutral
```

## Components

### Local Investigation Service

- [Flask Host & Orchestrator](https://github.com/octopus237/agentic-ai/blob/main/app.py): Flask application · Hosts UI/API, controls runs, streaming, scheduling, and managed process lifecycle. · `app.py`
- [Auto-run Scheduler](https://github.com/octopus237/agentic-ai/blob/main/app.py): scheduled triage · `app.py`
- [Investigation Loop](https://github.com/octopus237/agentic-ai/blob/main/agent_tools.py): agent runtime · Enforces step budget and cancellation while iterating model tool calls. · `agent_tools.py`
- [Constrained Tools](https://github.com/octopus237/agentic-ai/blob/main/agent_tools.py): tool boundary · Executes repository-controlled Wazuh queries and records calls. · `agent_tools.py`
- [Reports & Audit History](https://github.com/octopus237/agentic-ai/blob/main/app.py): JSON-backed history · Stores verdicts and tool-call trails; capped at 50 reports. · `app.py`
- [Wazuh Client](https://github.com/octopus237/agentic-ai/blob/main/client.py): data access layer · Normalizes authenticated responses from Wazuh services. · `client.py`

### External Services

- **Ollama Model**: LLM service · Selects tools and produces the final investigative answer.
- **Wazuh Indexer API**: external API :9200 · Provides alerts, aggregations, and event timelines.
- **Wazuh Server API**: external API :55000 · Provides live host inventory through token authentication.

### Other components

- **Analyst Browser**: user interface · Submits questions and views live investigation results.
- **Environment Configuration**: runtime configuration · Supplies endpoints, credentials, TLS settings, host, and port.

## Connections

- Analyst Browser → Flask Host & Orchestrator: questions / UI requests
- Flask Host & Orchestrator → Analyst Browser: progress and reports
- Auto-run Scheduler → Flask Host & Orchestrator: starts triage
- Flask Host & Orchestrator → Investigation Loop: starts / cancels run
- Investigation Loop → Ollama Model: prompt and tool definitions
- Ollama Model → Investigation Loop: tool calls / final answer
- Investigation Loop → Constrained Tools: executes requested tools
- Constrained Tools → Wazuh Client: query operations
- Wazuh Client → Wazuh Indexer API: basic-auth queries
- Wazuh Client → Wazuh Server API: token-auth inventory
- Constrained Tools → Investigation Loop: observations and audit calls
- Investigation Loop → Reports & Audit History: verdict and tool trail
- Flask Host & Orchestrator → Reports & Audit History: presents saved reports
- Environment Configuration → Flask Host & Orchestrator: UI host / port
- Environment Configuration → Investigation Loop: model settings
- Environment Configuration → Wazuh Client: endpoints and credentials