How jaycedowns42/upsonic works
Project type and purpose
• Upsonic is a Python-based, reliability-focused AI agent framework. It provides:
• A Client SDK for building and invoking agents
• A Main Server API to host agent workflows and reliability layers
• A Tools Server for secure, isolated tool execution (including MCP tools)
• Storage and caching modules for configuration and runtime data
• A Reliability Processor that orchestrates verifier/editor agents and iterative loops
Main components
A. Client SDK (src/upsonic/client, Direct, Task, Agent, MultiAgent)
B. Main Server API (src/upsonic/server/api.py, run_main_server.py)
C. Tools Server (src/upsonic/tools_server/server/api.py, run_tools_server.py)
D. Reliability Processor (src/upsonic/reliability_processor.py)
E. Storage Layer (src/upsonic/storage: caching, folder, configuration)
F. External Dependencies
• LLM Providers (OpenAI, Anthropic)
• MCP Servers (third-party Model Context Protocol servers)
• Telemetry endpoint (anonymous usage data)
Component relationships and data flow
1. Client Library
• The developer’s code calls Agent/Task or Direct →
• If using Agent → HTTP/gRPC to Main Server API
2. Main Server API
• Receives request → orchestrates Reliability Processor
• Reliability Processor sets up verifier/editor agents and loops →
• Calls into level_one / level_two server modules →
• May delegate tool calls to Tools Server
• Stores or retrieves interim data via Storage Layer
• For external knowledge, calls MCP or direct LLM endpoints
3. Tools Server
• Exposes secure API for invoking Python-defined tools or MCP tools
• Runs in isolated runtime environment
• Returns results to Main Server
4. External Services
• Main Server / Direct module → HTTP → LLM Providers
• Main Server / Tools Server → HTTP → MCP Servers
• Telemetry Collector receives usage events asynchronously
Architectural patterns and design principles
• Layered Architecture:
• Client Layer, API Layer, Reliability Layer, Tooling Layer, Storage Layer
• Microservices:
• Main Server and Tools Server run as separate Docker services
• Plugin/Adapter Pattern:
• MCP and custom Python functions as interchangeable “tools”
• Iterative Feedback Loops:
• Verifier and Editor agents in a triangular reliability pattern
• Pydantic Data Models:
• Structured inputs/outputs (ObjectResponse) for strong typing and validation
Technologies and frameworks
• Python 3.10+
• FastAPI (or similar) for server api.py
• Docker for containerization
• GitHub Actions for CI/CD (unit_tests.yml, publish.yml)
• pytest for tests (pytest.ini)
• Pre-commit hooks (.pre-commit-config.yaml)
• pyproject.toml for packaging