# jillesca/sp_oncall architecture

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

- Interactive diagram: https://gitdiagram.com/jillesca/sp_oncall
- Repository: https://github.com/jillesca/sp_oncall

## Overview

##### Project Type & Purpose
- SP Oncall is an open-source, agent-based backend tool (no GUI front end) for automating network device diagnostics.
- It uses LangGraph to orchestrate a directed graph of specialized “agent” nodes (planner, executor, assessor, reporter, etc.) and integrates with an external MCP tool (gNMIBuddy) and an LLM API (OpenAI or compatible).

##### File Structure & Architectural Patterns
- Top-level:
- architecture/ – design docs and phased workshop guides
- src/ – core Python packages
- plans/ & langgraph.json/mcp_config.json – JSON definitions for network checks and graph config
- tests/ – unit tests for executor nodes
- src/ layers:
- configuration: loading env vars, MCP tool config, LangChain settings
- graph.py: entry point that loads langgraph.json, builds & runs the agent graph
- mcp_client.py: generic client for MCP-based tools (e.g., gNMIBuddy)
- nodes/: individual node implementations (input_validator, planner, executor, assessor, reporter)
- prompts/ & schemas/: prompt templates + JSON schemas for I/O validation
- logging/: configurable, pluggable logging core, formatters, decorators, suppression strategies
- util/: helper modules (file_loader, LLM wrapper, plan utilities)
- Architectural pattern:
- Modular pipeline of agents in a directed acyclic graph (DAG)
- Separation of concerns: config, orchestration, node logic, prompts/schemas, logging, utilities
- External integrations: LLM API (over HTTP), MCP tool (via stdio)

##### Key Components
a. Core Orchestrator
- LangGraph engine (graph loader/executor)
- langgraph.json (defines nodes & edges)
- InputValidator → Planner → Executor → Assessor → Reporter
c. Configuration Layer
- .env / mcp_config.json / pyproject.toml / plans/*.json
d. Logging Subsystem
- logging/configuration → core → decorators → suppression
e. Utilities & Schemas
- util/ and schemas/: shared helpers & validation
f. External Services
- LLM API (OpenAI or LangSmith endpoint)
- gNMIBuddy via MCP protocol

##### Relationships & Data Flows
1. Startup: Orchestrator reads langgraph.json & plans → instantiates nodes
2. InputValidator validates user objectives via schema → passes to Planner
3. Planner constructs a plan (using planner prompt + schemas)
4. Executor invokes mcp_client → calls gNMIBuddy → collects device data
5. Assessor processes data + LLM API calls (via util/llm) → evaluates health
6. Reporter generates final report (report_generator prompt)
7. All steps emit structured logs → Logging subsystem
- Config injection flows into Orchestrator & mcp_client

##### Architectural Patterns & Principles
- Pipeline / DAG of specialized agents
- Dependency injection via configuration files / environment variables
- Layered structure (Orchestration → Nodes → Utilities)
- Pluggable logging & suppression strategies

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration" 
        direction TB
        CFG_ENV[/".env.example"/]:::config
        CFG_PY["pyproject.toml"]:::config
        CFG_MCP["mcp_config.json"]:::config
        CFG_PLANS[/plans/*.json/]:::config
        CFG_SRC["src/configuration.py"]:::src
    end

    %% Orchestration & Graph
    subgraph "Orchestration & Graph"
        direction TB
        LG_JSON[/langgraph.json/]:::config
        ORCH["src/graph.py"]:::src
    end

    %% Node Implementations
    subgraph "Node Implementations"
        direction TB
        IV["InputValidator"]:::src
        PL["Planner"]:::src
        EX["Executor"]:::src
        AS["Assessor"]:::src
        RP["Reporter"]:::src
    end

    %% Logging Subsystem
    subgraph "Logging"
        direction TB
        LOG_CFG["configuration"]:::src
        LOG_CORE["core"]:::src
        LOG_DEC["decorators"]:::src
        LOG_SUP["suppression"]:::src
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        LLM["LLM API\n(OpenAI/LangSmith)"]:::external
        MCP["gNMIBuddy\n(MCP stdio)"]:::external
        MCP_CLIENT["src/mcp_client.py"]:::src
    end

    %% Data Flows
    CFG_ENV -->|loads| ORCH
    CFG_PY -->|metadata| ORCH
    CFG_MCP -->|config| MCP_CLIENT
    CFG_PLANS -->|plans definitions| ORCH
    CFG_SRC -->|injects config| ORCH

    LG_JSON -->|graph config| ORCH
    ORCH -->|init DAG| IV
    IV -->|"validated objectives"| PL
    PL -->|"plan JSON"| EX
    EX -->|"device data"| AS
    AS -->|"health eval"| RP
    %% Logging integration
    ORCH -.->|logs| LOG_CFG
    IV -.->|logs| LOG_CORE
    PL -.->|logs| LOG_DEC
    EX -.->|logs| LOG_SUP
    AS -.->|logs| LOG_CORE
    RP -.->|logs| LOG_DEC

    %% External calls
    PL -->|uses prompts/schemas| CFG_PLANS
    EX -->|MCP stdio| MCP
    EX -->|via| MCP_CLIENT
    AS -->|LLM request/response| LLM

    %% Click Events
    click ORCH "https://github.com/jillesca/sp_oncall/blob/main/src/graph.py"
    click LG_JSON "https://github.com/jillesca/sp_oncall/blob/main/langgraph.json"
    click IV "https://github.com/jillesca/sp_oncall/blob/main/src/nodes/input_validator.py"
    click PL "https://github.com/jillesca/sp_oncall/blob/main/src/nodes/planner.py"
    click EX "https://github.com/jillesca/sp_oncall/blob/main/src/nodes/executor.py"
    click AS "https://github.com/jillesca/sp_oncall/blob/main/src/nodes/assessor.py"
    click RP "https://github.com/jillesca/sp_oncall/blob/main/src/nodes/reporter.py"
    click CFG_SRC "https://github.com/jillesca/sp_oncall/blob/main/src/configuration.py"
    click CFG_MCP "https://github.com/jillesca/sp_oncall/blob/main/mcp_config.json"
    click CFG_PY "https://github.com/jillesca/sp_oncall/blob/main/pyproject.toml"
    click CFG_PLANS "https://github.com/jillesca/sp_oncall/blob/main/plans/*.json"
    click CFG_ENV "https://github.com/jillesca/sp_oncall/blob/main/.env.example"
    click MCP_CLIENT "https://github.com/jillesca/sp_oncall/blob/main/src/mcp_client.py"

    %% Legend
    subgraph "Legend"
        direction TB
        A["Blue: Source modules"]:::src
        B["Gray: Config files"]:::config
        C["Green: External systems"]:::external
    end

    classDef src fill:#D0E8FF,stroke:#0366d6,stroke-width:1px,shape:rounded_rectangle
    classDef config fill:#F0F0F0,stroke:#888888,stroke-width:1px,shape:parallelogram
    classDef external fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px,shape:rectangle
```
