Upsonic

Upsonic provides a Task class that encapsulates LLM requests with description, context, tools, and response formatting, then executes them through either the Agent class (with reliability validation) or Direct class (simple LLM calls). The framework abstracts the execution pattern selection, allowing developers to define what they want accomplished independently of how it's executed, with built-in tracking of tool calls, execution duration, and estimated costs.

Upsonic implements a ReliabilityProcessor that wraps LLM outputs with automated validation and correction mechanisms, re-prompting the model to fix errors or inconsistencies detected in the response. The reliability layer operates as a post-processing step after initial LLM execution, using the same model or a different one to verify outputs against task requirements and response format specifications, with configurable retry limits and validation strategies.

Upsonic supports multi-agent workflows where multiple Agent instances can be orchestrated together through the Graph system, with shared context and coordinated execution. Agents can pass outputs to each other as context, enabling collaborative problem-solving where each agent specializes in a different task. The framework handles context marshalling between agents and provides visibility into the entire multi-agent execution trace.

Upsonic provides a Direct class that enables simple, direct LLM calls without the overhead of the full agent framework (no reliability layer, no graph orchestration). This is useful for straightforward LLM interactions where the full framework features are unnecessary. Direct calls still support tool integration, context, and response format specification, but skip the validation and correction steps.

Upsonic provides built-in error handling and debugging capabilities through execution traces that record all task executions, tool calls, and decision points. When errors occur, developers can inspect the full execution history to understand what went wrong. The framework supports custom error handlers and provides detailed error messages with context about the failing task.

Upsonic provides native support for Model Context Protocol (MCP) tools, allowing agents to call external tools through a standardized interface. Tools are registered on Task objects as a list, validated at execution time, and invoked through the LLM's function-calling API with automatic schema generation and parameter marshalling. The framework supports both MCP-compliant tools and Python functions, with tool calls recorded in the Task's tool_calls history for audit and debugging.

Upsonic abstracts multiple LLM providers (OpenAI, Anthropic, Ollama, etc.) through a unified Model interface using the strategy pattern. Developers specify a model as a string (e.g., 'openai/gpt-4') and the framework automatically routes requests to the correct provider, handling authentication, API differences, and response normalization. Model selection can be configured globally or per-Agent, with support for fallback providers and cost estimation across different models.

Upsonic allows Tasks to include context from multiple sources (strings, documents, knowledge bases) which are automatically injected into the LLM prompt. The framework supports RAG-enabled knowledge bases where context is retrieved based on semantic similarity to the task description, with configurable retrieval strategies and context window management. Context is processed and formatted before being passed to the LLM, with support for both unstructured text and structured knowledge base queries.

Upsonic provides a Graph system for composing multiple Tasks into complex workflows with decision nodes and branching logic. Graphs define a directed acyclic workflow where Tasks are nodes and edges represent dependencies and data flow. Decision nodes enable conditional branching based on Task outputs, allowing workflows to adapt dynamically. The framework handles task sequencing, context passing between tasks, and parallel execution where possible, with built-in error handling and rollback capabilities.

Upsonic's Direct class supports both synchronous (blocking) and asynchronous (non-blocking) task execution through separate methods, allowing developers to choose based on their application architecture. Asynchronous execution uses Python's asyncio, enabling concurrent task processing and integration with async frameworks (FastAPI, etc.). The framework also supports streaming responses where the LLM output is returned incrementally, enabling real-time UI updates and reduced latency perception.

Upsonic allows developers to create custom tools by wrapping Python functions with type hints and docstrings, which are automatically converted to MCP-compatible schemas for LLM function calling. Custom tools are registered on Task objects and executed within the agent's execution context, with automatic parameter marshalling and error handling. The framework supports both simple functions and complex tools with multiple parameters, return types, and side effects.

Upsonic allows Tasks to specify expected response formats as either Pydantic types or string schemas, which are validated against actual LLM outputs. The framework supports both unstructured text responses and structured outputs (JSON, dataclasses, etc.), with automatic parsing and validation. If validation fails, the reliability layer can be configured to re-prompt the LLM to correct the output format.

Upsonic automatically tracks and estimates costs for all LLM API calls, recording token usage and estimated USD cost on each Task object. The framework maintains a cost model for each supported provider and model, calculating costs based on input and output token counts. Developers can query total costs across multiple tasks, enabling cost-aware decision making and budget monitoring.