# deltaplanoo/agentic-probability-engine architecture

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

- Interactive diagram: https://gitdiagram.com/deltaplanoo/agentic-probability-engine
- Repository: https://github.com/deltaplanoo/agentic-probability-engine

## Overview

##### What this project is (from tree + README)
This repository is a **small Python client–server system** for “data-driven agentic probability assessment.” With only:
- `server.py` (service entrypoint)
- `client.py` (consumer/driver entrypoint)
- `requirements.txt` (Python deps)
it’s almost certainly a **single service** that exposes some API (HTTP, gRPC, or raw sockets) and a **client** that calls it to request probability assessments (likely providing data/features and receiving scores/uncertainty).

- the public interface in `server.py` (routes/handlers, request/response schemas)
- the call pattern in `client.py` (how it connects, what it sends, what it expects back)
- runtime dependencies in `requirements.txt` (FastAPI/Flask, requests, pydantic, numpy/pandas/sklearn, etc.)

##### Inspect `requirements.txt` to identify the “platform layer”
This tells you the type of server:
- **Flask/gunicorn** → HTTP JSON API (WSGI)
- **grpcio** → gRPC
- **websockets** → websocket server
- **requests/httpx** in client → HTTP client
- **numpy/pandas/scikit-learn/torch** → local model/analytics pipeline in server
- **openai/langchain** → “agentic” reasoning via external LLM APIs

##### Inspect `server.py` to identify runtime components
You’re looking for:
- **Server transport**: how it listens (host/port), protocol (HTTP, socket), endpoints.
- **Core pipeline**: functions/classes that transform input → features → probability estimate.
- **State**: in-memory caches, loaded model artifacts, config, environment variables.
- **I/O boundaries**: file reads (datasets, model weights), DB usage, external API calls.

##### Inspect `client.py` to identify the interaction contract
Extract:
- How it authenticates (API key? none?)
- What requests look like (payload fields)
- Whether it runs in batch mode (reads a file/dataset) or interactive mode
- Retry/timeouts, streaming, concurrency

##### Client process (`client.py`)
- Python runtime
- Dependency: `requests/httpx/grpcio` etc.
##### Server process (`server.py`)
- Python runtime
- Web framework (FastAPI/Flask/etc.)
- ML/agent libraries (sklearn/torch/langchain/etc.)
##### Data/Model artifacts (only if used)
- Local files: dataset CSV/JSON, model pickle, prompt templates
##### External services (only if used)
- LLM API, vector DB, metrics, etc.

If the server is single-process and stateful (loads model into memory), annotate that clearly.

Break the server into as many components as the code naturally allows. Typical “agentic probability assessment” server might decompose as:
- **API Layer / Handlers**
- `POST /assess` or equivalent
- **Request Validation / Schema**
- pydantic/dataclasses/manual checks
- **Assessment Orchestrator**
- coordinates steps (“agentic” loop, tool calls, reasoning stages)
- **Feature Extraction / Data Prep**
- normalization, parsing, missing values
- **Model/Estimator**
- statistical model / ML model / heuristic estimator
- **Calibration / Post-processing**
- confidence calibration, thresholds, explanation generation
- **Persistence / Logging (optional)**
- writes results, audit logs, metrics

- **Protocol**: HTTP JSON / gRPC / TCP socket
- **Key operations**:
- “Submit assessment request (data/features)”
- “Return probability + metadata (confidence, explanation, trace)”
- **Data flow direction**:
- client → server: request payload
- server → client: response payload
- If server calls externals:
- server → External API: “tool call / LLM inference / retrieval”
- External API → server: results

If the client reads inputs from disk and sends them:
- File/Data Source → client → server.

##### Architectural patterns to highlight (based on likely structure)
- **Client–Server** with a **thin client** and a **single service** performing compute.
Potential secondary patterns to annotate only if they exist in code:
- **Pipeline** (staged transformations)
- **Orchestrator/Agent loop** (planner → tool execution → aggregation)
- **Stateless vs stateful service**
- Stateless: each request independent
- Stateful: loaded model/caches in memory across requests

##### Technologies to include (how to decide accurately)
- Server framework (FastAPI/Flask/etc.)
- Client HTTP library (requests/httpx)
- ML stack (numpy/pandas/sklearn/torch)
- Agent/LLM stack (langchain/openai)
- Serialization (pydantic/json)
- Deployment runtime (uvicorn/gunicorn)

- “HTTP API Server (Python; framework TBD from requirements)”
and then replace once confirmed.

##### In `server.py`, identify
- entrypoint (app creation / socket bind)
- endpoints / message handlers
- main assessment function(s)
- external calls / file reads
##### In `client.py`, identify
- how it constructs requests
- input sources and output sinks
- endpoint names, ports, protocols, filenames.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 1: System Context
    %% =========================
    User["User / Analyst / Upstream System"]:::actor

    subgraph "Probability Assessment System (Python client–server)"
        Client["Probability Assessment Client\n(client.py)\nCLI / batch runner"]:::compute
        Server["Probability Assessment Server\n(server.py)\nAssessment API service"]:::compute

        subgraph "Platform & Dependencies"
            Deps["Dependency & Platform Layer\n(requirements.txt)\n(server/client frameworks + libs)"]:::meta
        end
    end

    Docs["Project Overview / Usage Docs\n(README.md)"]:::meta

    %% External services/data are optional/unknown from description
    External["External Providers (optional)\nLLM API / Data sources / Tools\n(only if present in code)"]:::external
    Artifacts[("Model/Data Artifacts (optional)\nCSV/JSON/model.pkl/prompts\n(only if loaded by server)")]:::data

    %% Context flows
    User -->|"runs_cli_or_batch"| Client
    User -->|"reads_usage_instructions"| Docs
    Client -->|"request_probability_assessment\n(protocol_TBD: HTTP_JSON/gRPC/TCP)"| Server
    Server -->|"response_probability_and_metadata\n(probability/confidence/explanation)"| Client

    Server -.->|"load_or_read (optional)"| Artifacts
    Server -.->|"tool_call_or_inference (optional)"| External

    %% =========================
    %% Level 3: Server Components (logical decomposition)
    %% =========================
    subgraph "Server internals (logical components within server.py)"
        direction TB;
        Api["API Layer / Handlers\n(e.g., POST /assess)"]:::api
        Schema["Request Validation / Schema\n(pydantic/dataclasses/manual)"]:::component
        Orchestrator["Assessment Orchestrator\n(agentic loop / step coordinator)"]:::component
        Features["Feature Extraction / Data Prep\n(parse/normalize/impute)"]:::component
        Estimator["Model / Estimator\n(statistical/ML/heuristic)"]:::component
        Post["Calibration / Post-processing\n(confidence/explanations/thresholds)"]:::component
        Obs["Logging / Metrics (optional)"]:::component
        State["In-memory State (optional)\nloaded_model/caches/config"]:::data
    end

    %% Server internal flow (vertical pipeline)
    Server -->|"dispatch_to_handler"| Api
    Api -->|"validate_input"| Schema
    Schema -->|"invoke_pipeline"| Orchestrator
    Orchestrator -->|"prepare_features"| Features
    Features -->|"estimate_probability"| Estimator
    Estimator -->|"post_process"| Post
    Post -->|"emit_result"| Api

    Orchestrator -.->|"read_cached_state (optional)"| State
    Server -.->|"initialize_state_on_startup (optional)"| State
    Server -.->|"emit_logs (optional)"| Obs

    %% Optional I/O boundaries
    Features -.->|"read_data (optional)"| Artifacts
    Estimator -.->|"load_weights (optional)"| Artifacts
    Orchestrator -.->|"external_tool_calls (optional)"| External

    %% Docs relationship
    Docs -.->|"documents_run_and_api_contract"| Client
    Docs -.->|"documents_server_startup"| Server

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click Server "https://github.com/deltaplanoo/agentic-probability-engine/blob/main/server.py"
    click Client "https://github.com/deltaplanoo/agentic-probability-engine/blob/main/client.py"
    click Deps "https://github.com/deltaplanoo/agentic-probability-engine/blob/main/requirements.txt"
    click Docs "https://github.com/deltaplanoo/agentic-probability-engine/blob/main/README.md"

    %% =========================
    %% Styles (color is critical)
    %% =========================
    classDef actor fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,color:#111827
    classDef compute fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1B4D
    classDef api fill:#C7D2FE,stroke:#4338CA,stroke-width:1.5px,color:#111827
    classDef component fill:#E0E7FF,stroke:#6366F1,stroke-width:1px,color:#111827
    classDef data fill:#D1FAE5,stroke:#059669,stroke-width:1.5px,color:#064E3B
    classDef external fill:#FEE2E2,stroke:#DC2626,stroke-width:1.5px,color:#7F1D1D
    classDef meta fill:#FEF3C7,stroke:#D97706,stroke-width:1.5px,color:#7C2D12
```
