YosrAI SDK

A lightweight, engine-first framework for building Agentic AI in Python.

YosrAI provides a clean, fluent API to build Agents, Workflows, and ReAct loops without the bloat. It is designed for developers who want to start small and scale fast, prioritizing clarity and control over magic.

⚡ Key Features

• Engine First: Explicit ReAct loops, no hidden prompts.
• Cost Transparency: Real-time token and cost tracking across all LLM providers.
• Agent Presets: One-liner specialized agents (researcher, writer, critic, coder, etc.).
• CLI Tool: Command-line interface for blueprint validation, execution, and diagramming.
• Conversation Mode: Natural multi-turn conversations with automatic history management.
• Thinking & Reflection: Built-in chain-of-thought and self-critique loops.
• Advanced RAG: Semantic memory with local vector search and text chunking.
• Multi-Modal: Native support for Image input (OpenAI, Anthropic, Google).
• Async Native: High-performance async/await support for high-throughput workflows.
• Resilient: Built-in retries (exponential backoff) and unified error handling.
• Observable: Beautiful, real-time rich console logging.
• Stateful: Serialize and resume workflows with ease.

🚀 Quick Start

Installation

# Using uv (Recommended)
uv pip install -e .

# Or standard pip
pip install -e .

Usage

1. The Basics

import os
from yosrai.engine import Agent, AgentConfig, Context

# Configure (Optional)
config = AgentConfig(
    model="gpt-4o",
    temperature=0.0,
    max_turns=5
)

# Create Agent
agent = Agent(
    name="Researcher",
    instructions="You are a helpful research assistant.",
    config=config
)

# Run
context = Context(input="What is the capital of France?")
response = agent.run(context)
print(response)

2. Async & Tools

import asyncio
from yosrai.engine import Agent, tool, Context

@tool
async def get_weather(city: str) -> str:
    return f"The weather in {city} is Sunny."

async def main():
    agent = Agent(
        name="WeatherBot",
        instructions="Help users check the weather.",
        tools=[get_weather],
        model="ollama/llama3"
    )

```python
    response = await agent.arun(Context(input="Weather in Cairo?"))
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

3. Human-in-the-Loop

Inject human feedback directly into your workflow using HumanAgent.

from yosrai.engine.human import HumanAgent
from yosrai.engine import Workflow, Agent

# Define Agents
analyst = Agent(name="Analyst", instructions="Analyze the data.")
reviewer = HumanAgent(name="Editor", instructions="Review the analysis. Type 'APPROVE' or give feedback.")
writer = Agent(name="Writer", instructions="Write final report based on analysis and feedback.")

# Chain them
pipeline = Workflow("ReviewPipeline")
pipeline.start(analyst).then(reviewer).then(writer)

# Run (Interactive)
pipeline.run(input="Analyze Q1 Sales.")

4. Agent Presets

Get started instantly with pre-configured agents for common tasks.

from yosrai import Agent

# One-liner agents for common patterns
researcher = Agent.from_preset("researcher")
writer = Agent.from_preset("writer")
critic = Agent.from_preset("critic")

# Ready to use immediately
result = researcher.run("Explain quantum computing")
print(result)

5. Cost Tracking

Monitor your LLM usage and costs in real-time.

from yosrai import Agent

agent = Agent.from_preset("assistant")

# Run with automatic cost tracking
result = agent.run("Write a summary of AI trends")
print(f"Cost: ${agent.last_usage.cost:.4f}")
print(f"Tokens: {agent.last_usage.total_tokens}")

6. Conversation Mode

Natural multi-turn conversations with automatic history management.

from yosrai import Agent

agent = Agent.from_preset("assistant")

# Start a conversation
with agent.conversation() as chat:
    response1 = chat.send_message("Hello!")
    response2 = chat.send_message("What's your name?")
    print(f"Total cost: ${chat.total_usage.cost:.4f}")

7. CLI Tool

Command-line interface for blueprint validation, execution, and more.

# Validate blueprints before deployment
yosrai validate blueprints/ --recursive --json

# Execute agents from blueprints
yosrai run agent_blueprint.json --input "Hello world"

# Generate visual diagrams
yosrai diagram workflow_blueprint.json -o docs/diagram.md

# Interactive chat with presets
yosrai chat --preset researcher --save-session chat.json

8. Built-in Toolkits

Use ready-made tools for common tasks like Web Search and File I/O.

from yosrai.toolkit import WebToolkit
from yosrai.engine import Agent

# Get DuckDuckGo search tools
web_tools = WebToolkit(max_results=3).get_tools()

researcher = Agent(
    name="Researcher",
    instructions="Find the latest AI news.",
    tools=web_tools,
    model="openai/gpt-4o"
)

researcher.run("What happened in AI this week?")

🧩 Core Concepts

• Agent: An autonomous actor with Instructions (Identity), Tools (Hands), and LLM (Voice).
• Workflow: A fluent orchestrator to chain agents (.start().then().choice()).
• Context: A shared "blackboard" state for your workflow.
• Config: Typed configuration for predictable behavior.