Skip to content

Getting Started with YosrAI

This guide will help you get up and running with YosrAI quickly. We'll cover installation, basic setup, and create your first AI agent.

Installation

Prerequisites

  • Python 3.9 or higher
  • pip (Python package installer)
  • A valid API key from at least one supported LLM provider (e.g., OpenAI, Anthropic)

Install YosrAI

pip install yosrai

For development installation with all optional dependencies:

pip install "yosrai[dev]"

Basic Setup

1. Configure Your Environment

Create a .env file in your project root:

OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
# Add other provider keys as needed

Or set environment variables directly:

import os
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

2. Create Your First Agent

Here's a simple example to create and use an AI agent:

from yosrai.core import Agent, LLM

# Initialize an agent
agent = Agent(
    agent_code="assistant",
    agent_name="My First Assistant",
    llm=LLM(provider="openai", model="gpt-3.5-turbo")
)

# Use the agent
async def main():
    response = await agent.act("Tell me a joke about programming!")
    print(response)

# Run the async function
import asyncio
asyncio.run(main())

Basic Concepts

1. Working with LLMs

Configure different language models:

from yosrai.core import LLM

# OpenAI configuration
llm_openai = LLM(
    provider="openai",
    model="gpt-4",
    temperature=0.7
)

# Anthropic configuration
llm_anthropic = LLM(
    provider="anthropic",
    model="claude-2",
    temperature=0.5
)

2. Managing Context

Use context to maintain state and history:

from yosrai.core import Context

# Create context
context = Context(
    system_prompt="You are a helpful programming assistant",
    user_name="Alice",
    messages=[]
)

# Use context with agent
async def chat():
    response = await agent.act(
        "Help me with Python!",
        context=context()
    )

3. Creating Actions

Define workflows with multiple agents:

from yosrai.core import Action, Agent

# Create specialized agents
researcher = Agent(
    agent_code="researcher",
    agent_name="Research Assistant",
    llm=LLM(provider="openai")
)

writer = Agent(
    agent_code="writer",
    agent_name="Content Writer",
    llm=LLM(provider="anthropic")
)

# Create an action
action = Action(
    action_name="Content Creation",
    action_description="Research and write content"
)

# Set up workflow
action.Context(messages=[])
action.add_agent(researcher)
action.add_agent(writer)
action.add_link(researcher, writer)
action.add_link(writer, "END")

# Run the workflow
async def create_content():
    await action.run()

Common Patterns

1. Streaming Responses

Enable streaming for real-time responses:

async def stream_handler(chunk: str):
    print(chunk, end="", flush=True)

response = await agent.act(
    "Write a story...",
    streaming=True,
    streaming_callback=stream_handler
)

2. Using Tools

Add capabilities to your agents:

# Define a tool
calculator_tool = {
    "name": "calculator",
    "func": lambda x, y: x + y,
    "description": "Add two numbers"
}

# Enable tools for agent
agent.UseTools = True
agent.bind_tools([calculator_tool])

3. Template Usage

Use templates for dynamic prompts:

agent = Agent(
    agent_code="teacher",
    agent_name="Math Teacher",
    instructions_template="You are a math teacher explaining {{ topic }}",
    prompt_template="Please explain {{ concept }} in simple terms."
)

response = await agent.interact({
    "topic": "algebra",
    "concept": "quadratic equations"
})

Next Steps

After mastering these basics, you can:

  1. Explore Core Components in detail
  2. Learn about Advanced Features
  3. Check out Example Projects
  4. Join our Community

Common Issues and Solutions

API Key Issues

from yosrai.utils.config import Config

# Load config from environment
config = Config.from_env()

# Or specify directly
config = Config(
    api_keys={
        "openai": "your-key",
        "anthropic": "your-key"
    }
)

Memory Management

# Clear context between runs
context.update(messages=[])

# Use session IDs for persistence
await action.run(session_id="unique_session")

Provider Selection

from yosrai.core import Providers

# List available providers
providers = Providers()
available = providers.list()

# Get provider models
models = providers.get_models("openai")

Best Practices

  1. Error Handling: Always wrap API calls in try-except blocks
  2. Context Management: Clear or update context appropriately
  3. Resource Cleanup: Close sessions and connections properly
  4. API Keys: Never hardcode API keys in your code
  5. Async Usage: Use proper async/await patterns

Getting Help