How jillesca/sp_oncall works
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