Skip to content

๐Ÿ—๏ธ GNS3-Copilot Backend Evolution Plan

1. Architectural Vision

Transition from a standalone Streamlit script to a "Dual-Engine" architecture.

  • Engine A (Legacy): Streamlit app.py for rapid internal prototyping and debugging.
  • Engine B (Modern): FastAPI server.py acting as a BFF (Backend for Frontend) to serve a modern React UI and mobile voice interaction.

2. Core Technical Strategy

  • Concurrency: Use FastAPI's standard def routes to leverage the internal thread pool for handling synchronous GNS3 API calls and LangGraph execution.
  • Configuration: Maintain .env driven settings (Local-First). Credentials (LLM Keys, GNS3 URL) are loaded via environment variables; no complex Auth required for local MVP.
  • Communication: Implement SSE (Server-Sent Events) for real-time AI "typing" effects and tool-calling status updates.
  • Voice Integration: Implement a "Relay" pattern: Browser Mic -> FastAPI -> Commercial STT (Whisper) -> LangGraph -> Commercial TTS -> Browser Speaker.

3. Implementation Roadmap

Phase 1: API Infrastructure (Foundation)

  • Goal: Establish the FastAPI project structure and enable cross-origin communication.
  • Tasks:
  • Install fastapi and uvicorn.
  • Create api/main.py with CORS middleware (essential for React).
  • Set up the router directory structure for scalability.

Phase 2: LangGraph Integration (The "Brain")

  • Goal: Expose the LangGraph agent as a unified, streaming API.
  • Tasks:
  • Develop the POST /agent/stream endpoint.
  • Wrap the synchronous graph.stream using asyncio.to_thread or an event-pumping queue.
  • Define a standard SSE message schema (e.g., type: text for content, type: tool for action status).

Phase 3: Voice Interaction Pipeline

  • Goal: Enable voice-to-command capabilities using commercial APIs.
  • Tasks:
  • Create POST /agent/voice-chat to receive audio files (.webm/.wav).
  • Integrate OpenAI Whisper API for STT (Speech-to-Text).
  • Connect transcribed text to the existing LangGraph logic and optionally return audio via TTS.

Phase 4: Project & Topology Services

  • Goal: Provide the frontend with GNS3 project metadata.
  • Tasks:
  • Implement GET /projects to list available GNS3 topologies.
  • Implement GET /projects/{id}/topology for React Flow visualization data.
src/gns3_copilot/
โ”œโ”€โ”€ api/
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ main.py              # Entry point & Middleware config
โ”‚   โ”œโ”€โ”€ dependencies.py      # Shared logic (Context/Config)
โ”‚   โ””โ”€โ”€ routers/
โ”‚       โ”œโ”€โ”€ __init__.py
โ”‚       โ”œโ”€โ”€ agent.py         # Chat, Streaming, and Voice endpoints
โ”‚       โ””โ”€โ”€ projects.py      # Project & Topology management
โ”œโ”€โ”€ tools/                   # Existing Sync GNS3 Tools (Unchanged)
โ”œโ”€โ”€ agent/                   # Existing LangGraph Logic (Unchanged)
โ””โ”€โ”€ .env                     # Local API Keys & GNS3 Server config

5. Current Sprint Checklist

  • [ ] Setup: Run pip install fastapi uvicorn pydantic-settings.
  • [ ] Scaffolding: Create the api/ directory and initialize main.py.
  • [ ] Core API: Implement the /agent/stream endpoint and verify via Swagger UI (/docs).
  • [ ] Testing: Ensure the API correctly reads .env variables without manual injection.