pavan1290/sigma

Purpose and Runtime Shape

SIGMA-OS is a local desktop-oriented intelligent-agent system: a React/Vite UI talks to a Python FastAPI service that routes natural-language tasks to system, email, and browser automation agents. An Electron main process packages/launches the application for Windows. Primary launch paths are start.sh, backend/app.py, src/main.jsx, and main.cjs.

Client and Desktop Shell

The interactive client is a React application centered on the assistant/chat experience, model selection, API-key management, formatted result display, and system status. It communicates with FastAPI through REST plus a WebSocket channel. Electron is the desktop boundary; shipped Windows artifacts embed the Python backend under release-fixed/win-unpacked/resources/app.asar.unpacked/backend/app.py.

• src/main.jsx

• src/App.jsx

• src/components/IntelligentAssistant.jsx

• main.cjs

API Gateway and Real-Time Control Plane

FastAPI is the application-facing backend, exposing health, model, API-key, command, and WebSocket endpoints (documented as port 5000 and /ws). It accepts UI/API commands, applies model and agent routing, and returns or streams execution updates. This is the key boundary between untrusted user requests and privileged automation.

• backend/app.py

• backend/models.py

• backend/db.py

Agent Routing and Execution

The agent core coordinates task interpretation and dispatch to capability-specific agents. SystemAgent handles local shell/files/processes/screenshots; EmailAgent handles Gmail operations; WebAgent drives browser automation. Their results are normalized for UI/MCP consumers rather than exposing raw execution details directly.

• intelligent_agents/agent_core.py

• intelligent_agents/system_agent.py

• intelligent_agents/email_agent.py

• intelligent_agents/web_agent.py

Model and Output Layer

Model management abstracts interchangeable inference providers and separates “thinking” from execution model selection. Provider keys come from environment/UI-managed configuration; supported integrations include Groq, Google Gemini, OpenAI, Anthropic, and local Ollama. Output formatting converts command and automation results into structured, display-oriented responses.

• intelligent_agents/model_manager.py

• intelligent_agents/output_formatter.py

• .env.example

MCP Integration Boundary

The MCP server publishes system, email, web, analysis, and model capabilities as standard callable tools for external LLM clients such as Claude. It is an alternate ingress/control path alongside FastAPI, delegating tool calls into the same agent capabilities.

• intelligent_agents/mcp_server.py

• intelligent_agents/__init__.py

Automation Workflows and Resilience

A separate backend automation subsystem supports orchestrated workflows, scheduled tasks, monitoring-triggered rules, retries, and recovery. Example JSON definitions indicate workflows/rules are data-driven inputs to this subsystem, distinct from single interactive agent commands.

• backend/automation/orchestrator.py

• backend/automation/workflow_engine.py

• backend/automation/rules_engine.py

• backend/automation/task_scheduler.py

• backend/automation/error_recovery.py

External Dependencies and Privilege Boundaries

Python 3.10+ hosts FastAPI and agents; Node.js runs Vite/React and Electron. Browser automation requires Playwright. System automation uses host-level facilities (shell, filesystem, process inspection, screenshots), while email crosses Gmail APIs and models cross external AI-provider APIs. These integrations make credential handling and command/tool authorization architecturally sensitive.