Only this pageAll pages
Powered by GitBook
Couldn't generate the PDF for 153 pages, generation stopped at 100.
Extend with 50 more pages.
1 of 100

Bitca

Getting Started

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Documentation

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Human UI

Bitca provides a beautiful Human UI for interacting with your humans.

Human Ambient

Let’s take it for a spin, create a file playground.py

playground.py

Authenticate with bitca

Authenticate with bitca by running the following command:

bitca auth

or by exporting the BITCA_API_KEY for your workspace from bitca.app

MacWindows

Run the playground

Install dependencies and run the Human Ambient:

View the playground

  • Open the link provided or navigate to http://projectbit.ca/ambient (login required)

  • Select the localhost:7777 endpoint and start chatting with your humans!

Demo Humans

The Human Ambient includes a few demo humans that you can test with. If you have recommendations for other humans we should build, please let us know in the community forum.

Humans

GitBook has a powerful block-based editor that allows you to seamlessly create, update, and enhance your content.

Writing content

GitBook offers a range of block types for you to add to your content inline — from simple text and tables, to code blocks and more. These elements will make your pages more useful to readers, and offer extra information and context.

Either start typing below, or press / to see a list of the blocks you can insert into your page.

Models

GitBook supports many different types of content, and is backed by Markdown — meaning you can copy and paste any existing Markdown files directly into the editor!

Feel free to test it out and copy the Markdown below by hovering over the code block in the upper right, and pasting into a new line underneath.

If you have multiple files, GitBook makes it easy to import full repositories too — allowing you to keep your GitBook content in sync.

Getting Help

Thank you for building with bitca. If you need help, please come chat with us on discord or post your questions on the community forum.

Looking for dedicated support?

We’ve helped many companies build AI products, the general workflow is:

  1. Build agents to perform tasks specific to your product.

Tools

GitBook allows you to add images and media easily to your docs. Simply drag a file into the editor, or use the file manager in the upper right corner to upload multiple images at once.

You can also add images simply by copying and pasting them directly into the editor — and GitBook will automatically add it to your file manager.

from bitca.human import Human
from bitca.model.openai import OpenAIChat
from bitca.storage.human.sqlite import SqlhumanStorage
from bitca.tools.duckduckgo import DuckDuckGo
from bitca.tools.yfinance import YFinanceTools
from bitca.playground import Playground, serve_playground_app

web_human = Human(
    name="Web Human",
    model=OpenAIChat(id="gpt-4o"),
    tools=[DuckDuckGo()],
    instructions=["Always include sources"],
    storage=SqlhumanStorage(table_name="web_human", db_file="humans.db"),
    add_history_to_messages=True,
    markdown=True,
)

finance_human = Human(
    name="Finance Human",
    model=OpenAIChat(id="gpt-4o"),
    tools=[YFinanceTools(stock_price=True, analyst_recommendations=True, company_info=True, company_news=True)],
    instructions=["Use tables to display data"],
    storage=SqlhumanStorage(table_name="finance_human", db_file="humans.db"),
    add_history_to_messages=True,
    markdown=True,
)

app = Ambient(humans=[finance_human, web_human]).get_app()

if __name__ == "__main__":
    serve_ambient_app("ambient:app", reload=True)

Serve your agents via an API and connect them to your product.

  • Monitor, evaluate and improve your AI product.

  • We provide dedicated support and development, book a call to get started. Our prices start at $20k/month and we specialize in taking companies from idea to production within 3 months.

    Functions

    Any python function can be used as a tool by an Agent. We highly recommend creating functions specific to your workflow and adding them to your Agents.

    For example, here’s how to use a get_top_hackernews_stories function as a tool:

    hn_agent.py

    import json
    import httpx
    
    from bitca.agent import Agent
    
    
    def get_top_hackernews_stories(num_stories: int = 10) -> str:
        """Use this function to get top stories from Hacker News.
    
        Args:
            num_stories (int): Number of stories to return. Defaults to 10.
    
        Returns:
            str: JSON string of top stories.
        """
    
        # Fetch top story IDs
        response = httpx.get('https://hacker-news.firebaseio.com/v0/topstories.json')
        story_ids = response.json()
    
        # Fetch story details
        stories = []
        for story_id in story_ids[:num_stories]:
            story_response = httpx.get(f'https://hacker-news.firebaseio.com/v0/item/{story_id}.json')
            story = story_response.json()
            if "text" in story:
                story.pop("text", None)
            stories.append(story)
        return json.dumps(stories)
    
    agent = Agent(tools=[get_top_hackernews_stories], show_tool_calls=True, markdown=True)
    agent.print_response("Summarize the top 5 stories on hackernews?", stream=True)

    Introduction

    Tools are functions that an Agent can run like searching the web, running SQL, sending an email or calling APIs. Use tools integrate Agents with external systems. You can use any python function as a tool or use a pre-built toolkit. The general syntax is:

    from bitca.agent import Agent
    
    agent = Agent(
        # Add functions or Toolkits
        tools=[...],
        # Show tool calls in the Agent response
        show_tool_calls=True
    )

    Read more about:

    • Available Toolkits

    • Using functions as tools

    setx BITCA_API_KEY bitca-***
    pip install 'fastapi[standard]' sqlalchemy
    
    python human.py
    Add a new block
    1

    Open the insert block menu

    Press / on your keyboard to open the insert block menu.

    2

    Search for the block you need

    Try searching for “Stepper”, for exampe, to insert the stepper block.

    3

    Insert and edit your block

    Click or press Enter to insert your block. From here, you’ll be able to edit it as needed.

    # Heading
    
    This is some paragraph text, with a [link](https://docs.gitbook.com) to our docs. 
    
    ## Heading 2
    - Point 1
    - Point 2
    - Point 3
    Add alt text and captions to your images

    Monitoring

    Bitca comes with built-in monitoring and debugging.

    You can set monitoring=True on any agent to log that agent’s sessions or set BITCA_MONITORING=true in your environment to log all agent sessions.

    Create a file monitoring.py with the following code: monitoring.py

    from bitca.agent import Agent
    
    agent = Agent(markdown=True, monitoring=True)
    agent.print_response("Share a 2 sentence horror story")

    Authenticate with bitca

    Authenticate with bitca by running the following command:

    bitca auth

    or by exporting the BITCA_API_KEY for your workspace from bitcadata.app

    Run the agent

    Run the agent and view the session on bitca.app/sessions

    Debugging

    Bitca also includes a built-in debugger that will show debug logs in the terminal. You can set debug_mode=True on any agent to view debug logs or set BITCA_DEBUG=true in your environment.

    debugging.py

    Run the agent to view debug logs in the terminal:

    Writing your own Toolkit

    Many advanced use-cases will require writing custom Toolkits. Here’s the general flow:

    1. Create a class inheriting the bitca.tools.Toolkit class.

    2. Add your functions to the class.

    3. Important: Register the functions using self.register(function_name)

    Now your Toolkit is ready to use with an Agent. For example:

    shell_toolkit.py

    Crawl4AI

    Crawl4aiTools enable an Agent to perform web crawling and scraping tasks using the Crawl4ai library.

    ​Prerequisites

    The following example requires the crawl4ai library.

    Example

    The following agent will scrape the content from the webpage:

    cookbook/tools/crawl4ai_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Newspaper

    NewspaperTools enable an Agent to read news articles using the Newspaper4k library.

    ​Prerequisites

    The following example requires the newspaper3k library.

    Example

    The following agent will summarize the wikipedia article on language models.

    cookbook/tools/newspaper_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Teams

    We can combine multiple Agents to form a team and tackle tasks as a cohesive unit. Here’s a simple example that uses a team of agents to write an article about the top stories on hackernews.

    hn_team.py

    Run the script to see the output.

    How to build Agent Teams

    1. Add a name

    Structured Output

    One of our favorite features is using Agents to generate structured data (i.e. a pydantic model). Use this feature to extract features, classify data, produce fake data etc. The best part is that they

    Example

    Let’s create an Movie Agent to write a MovieScript for us.

    movie_agent.py

    Run the script to see the output.

    The output is an object of the MovieScript class, here’s how it looks:

    Introduction

    Language Models are machine-learning programs that are trained to understand natural language and code. They provide reasoning and planning capabilities to Agents.

    Use any model with an Agent like:

    bitca supports the following model providers:

    Open AI Like

    Many providers like Together, Groq, Sambanova, etc support the OpenAI API format. Use the OpenAILike model to access them by replacing the base_url.

    Example

    agent.py

    File

    FileTools enable an Agent to read and write files on the local file system.

    Example

    The following agent will generate an answer and save it in a file.

    cookbook/tools/file_tools.py

    AWS Lambda

    Prerequisites

    The following example requires the boto3 library.

    Example

    Giphy

    GiphyTools enables an Agent to search for GIFs on GIPHY.

    Prerequisites

    Example

    The following agent will search GIPHY for a GIF appropriate for a birthday message.

    Jina Reader

    JinaReaderTools enable an Agent to perform web search tasks using Jina.

    Prerequisites

    The following example requires the jina library.

    Hacker News

    HackerNews enables an Agent to search Hacker News website.

    Example

    The following agent will write an engaging summary of the users with the top 2 stories on hackernews along with the stories.

    cookbook/tools/hackernews.py

    Nvidia

    Authentication

    Set your NVIDIA_API_KEY environment variable. Get your key .

    MacWindows

    Fireworks

    Fireworks is a platform for providing endpoints for Large Language models.

    Authentication

    Set your FIREWORKS_API_KEY environment variable. Get your key from .

    MacWindows

    pip install -U crawl4ai
    pip install -U newspaper3k
    export BITCA_API_KEY=bitca-***
    python monitoring.py
    from typing import List
    
    from bitca.tools import Toolkit
    from bitca.utils.log import logger
    
    
    class ShellTools(Toolkit):
        def __init__(self):
            super().__init__(name="shell_tools")
            self.register(self.run_shell_command)
    
        def run_shell_command(self, args: List[str], tail: int = 100) -> str:
            """Runs a shell command and returns the output or error.
    
            Args:
                args (List[str]): The command to run as a list of strings.
                tail (int): The number of lines to return from the output.
            Returns:
                str: The output of the command.
            """
            import subprocess
    
            logger.info(f"Running shell command: {args}")
            try:
                logger.info(f"Running shell command: {args}")
                result = subprocess.run(args, capture_output=True, text=True)
                logger.debug(f"Result: {result}")
                logger.debug(f"Return code: {result.returncode}")
                if result.returncode != 0:
                    return f"Error: {result.stderr}"
                # return only the last n lines of the output
                return "\n".join(result.stdout.split("\n")[-tail:])
            except Exception as e:
                logger.warning(f"Failed to run shell command: {e}")
                return f"Error: {e}"

    max_length

    int

    1000

    Specifies the maximum length of the text from the webpage to be returned.

    web_crawler

    Crawls a website using crawl4ai’s WebCrawler. Parameters include ‘url’ for the URL to crawl and an optional ‘max_length’ to limit the length of extracted content. The default value for ‘max_length’ is 1000.

    ​
    https://docs.projectbit.ca/
    ​
    ​

    get_article_text

    bool

    True

    Enables the functionality to retrieve the text of an article.

    get_article_text

    Retrieves the text of an article from a specified URL. Parameters include url for the URL of the article. Returns the text of the article or an error message if the retrieval fails.

    ​
    ​
    ​
    and
    role
    parameter to the member Agents.
  • Create a Team Leader that can delegate tasks to team-members.

  • Use your Agent team just like you would use a regular Agent.

  • from bitca.agent import Agent
    from bitca.tools.hackernews import HackerNews
    from bitca.tools.duckduckgo import DuckDuckGo
    from bitca.tools.newspaper4k import Newspaper4k
    
    hn_researcher = Agent(
        name="HackerNews Researcher",
        role="Gets top stories from hackernews.",
        tools=[HackerNews()],
    )
    
    web_searcher = Agent(
        name="Web Searcher",
        role="Searches the web for information on a topic",
        tools=[DuckDuckGo()],
        add_datetime_to_instructions=True,
    )
    
    article_reader = Agent(
        name="Article Reader",
        role="Reads articles from URLs.",
        tools=[Newspaper4k()],
    )
    
    hn_team = Agent(
        name="Hackernews Team",
        team=[hn_researcher, web_searcher, article_reader],
        instructions=[
            "First, search hackernews for what the user is asking about.",
            "Then, ask the article reader to read the links for the stories to get more information.",
            "Important: you must provide the article reader with the links to read.",
            "Then, ask the web searcher to search for each story to get more information.",
            "Finally, provide a thoughtful and engaging summary.",
        ],
        show_tool_calls=True,
        markdown=True,
    )
    hn_team.print_response("Write an article about the top 2 stories on hackernews", stream=True)
    ​
    from typing import List
    from rich.pretty import pprint
    from pydantic import BaseModel, Field
    from bitca.agent import Agent, RunResponse
    from bitca.model.openai import OpenAIChat
    
    
    class MovieScript(BaseModel):
        setting: str = Field(..., description="Provide a nice setting for a blockbuster movie.")
        ending: str = Field(..., description="Ending of the movie. If not available, provide a happy ending.")
        genre: str = Field(
            ..., description="Genre of the movie. If not available, select action, thriller or romantic comedy."
        )
        name: str = Field(..., description="Give a name to this movie")
        characters: List[str] = Field(..., description="Name of characters for this movie.")
        storyline: str = Field(..., description="3 sentence storyline for the movie. Make it exciting!")
    
    
    # Agent that uses JSON mode
    json_mode_agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        description="You write movie scripts.",
        response_model=MovieScript,
    )
    # Agent that uses structured outputs
    structured_output_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"),
        description="You write movie scripts.",
        response_model=MovieScript,
        structured_outputs=True,
    )
    
    
    # Get the response in a variable
    # json_mode_response: RunResponse = json_mode_agent.run("New York")
    # pprint(json_mode_response.content)
    # structured_output_response: RunResponse = structured_output_agent.run("New York")
    # pprint(structured_output_response.content)
    
    json_mode_agent.print_response("New York")
    structured_output_agent.print_response("New York")
    pip install -U bitca openai
    
    python movie_agent.py

    AWS Bedrock

  • Azure

  • Cohere

  • DeepSeek

  • Fireworks

  • Google

  • Groq

  • Mistral

  • Ollama

  • OpenAI Like

  • OpenRouter

  • Sambanova

  • Together

  • VertexAI

  • OpenAI
    Anthropic
    ​Params

    OpenAILike also support all the params of OpenAIChat

    from os import getenv
    from bitca.agent import Agent, RunResponse
    from bitca.model.openai.like import OpenAILike
    
    agent = Agent(
        model=OpenAILike(
            id="mistralai/Mixtral-8x7B-Instruct-v0.1",
            api_key=getenv("TOGETHER_API_KEY"),
            base_url="https://api.together.xyz/v1",
        )
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    ​
    ​Toolkit Params
    Parameter
    Type
    Default
    Description

    get_top_stories

    bool

    True

    Enables fetching top stories.

    get_user_details

    bool

    True

    Enables fetching user details.

    ​Toolkit Functions

    Function
    Description

    get_top_hackernews_stories

    Retrieves the top stories from Hacker News. Parameters include num_stories to specify the number of stories to return (default is 10). Returns the top stories in JSON format.

    get_user_details

    Retrieves the details of a Hacker News user by their username. Parameters include username to specify the user. Returns the user details in JSON format.

    ​
    The following agent will use AWS Lambda to list all Lambda functions in our AWS account and invoke a specific Lambda function.

    cookbook/tools/aws_lambda_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    region_name

    str

    "us-east-1"

    AWS region name where Lambda functions are located.

    ​Toolkit Functions

    Function
    Description

    list_functions

    Lists all Lambda functions available in the AWS account.

    invoke_function

    Invokes a specific Lambda function with an optional payload. Takes function_name and optional payload parameters.

    ​Information

    • View on Github

    ​

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    None

    If you want to manually supply the GIPHY API key.

    limit

    int

    1

    The number of GIFs to return in a search.

    ​Toolkit Functions

    Function
    Description

    search_gifs

    Searches GIPHY for a GIF based on the query string.

    ​
    ​
    from bitca.agent import Agent
    
    agent = Agent(markdown=True, debug_mode=True)
    agent.print_response("Share a 2 sentence horror story")
    python debugging.py
    from bitca.agent import Agent
    from bitca.tools.crawl4ai_tools import Crawl4aiTools
    
    agent = Agent(tools=[Crawl4aiTools(max_length=None)], show_tool_calls=True)
    agent.print_response("Tell me about https://github.com/bitca/bitca.")
    from bitca.agent import Agent
    from bitca.tools.newspaper_tools import NewspaperTools
    
    agent = Agent(tools=[NewspaperTools()])
    agent.print_response("Please summarize https://en.wikipedia.org/wiki/Language_model")
    pip install -U openai duckduckgo-search newspaper4k lxml_html_clean bitca
    
    python hn_team.py
    # Using JSON mode
    MovieScript(
    │   setting='The bustling streets of New York City, filled with skyscrapers, secret alleyways, and hidden underground passages.',
    │   ending='The protagonist manages to thwart an international conspiracy, clearing his name and winning the love of his life back.',
    │   genre='Thriller',
    │   name='Shadows in the City',
    │   characters=['Alex Monroe', 'Eva Parker', 'Detective Rodriguez', 'Mysterious Mr. Black'],
    │   storyline="When Alex Monroe, an ex-CIA operative, is framed for a crime he didn't commit, he must navigate the dangerous streets of New York to clear his name. As he uncovers a labyrinth of deceit involving the city's most notorious crime syndicate, he enlists the help of an old flame, Eva Parker. Together, they race against time to expose the true villain before it's too late."
    )
    
    # Use the structured output
    MovieScript(
    │   setting='In the bustling streets and iconic skyline of New York City.',
    │   ending='Isabella and Alex, having narrowly escaped the clutches of the Syndicate, find themselves standing at the top of the Empire State Building. As the glow of the setting sun bathes the city, they share a victorious kiss. Newly emboldened and as an unstoppable duo, they vow to keep NYC safe from any future threats.',
    │   genre='Action Thriller',
    │   name='The NYC Chronicles',
    │   characters=['Isabella Grant', 'Alex Chen', 'Marcus Kane', 'Detective Ellie Monroe', 'Victor Sinclair'],
    │   storyline='Isabella Grant, a fearless investigative journalist, uncovers a massive conspiracy involving a powerful syndicate plotting to control New York City. Teaming up with renegade cop Alex Chen, they must race against time to expose the culprits before the city descends into chaos. Dodging danger at every turn, they fight to protect the city they love from imminent destruction.'
    )
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        description="Share 15 minute healthy recipes.",
        markdown=True,
    )
    agent.print_response("Share a breakfast recipe.", stream=True)
    from bitca.agent import Agent
    from bitca.tools.hackernews import HackerNews
    
    agent = Agent(
        name="Hackernews Team",
        tools=[HackerNews()],
        show_tool_calls=True,
        markdown=True,
    )
    agent.print_response(
        "Write an engaging summary of the "
        "users with the top 2 stories on hackernews. "
        "Please mention the stories as well.",
    )
    pip install openai boto3
    
    from bitca.agent import Agent
    from bitca.tools.aws_lambda import AWSLambdaTool
    
    
    # Create an Agent with the AWSLambdaTool
    agent = Agent(
        tools=[AWSLambdaTool(region_name="us-east-1")],
        name="AWS Lambda Agent",
        show_tool_calls=True,
    )
    
    # Example 1: List all Lambda functions
    agent.print_response("List all Lambda functions in our AWS account", markdown=True)
    
    # Example 2: Invoke a specific Lambda function
    agent.print_response("Invoke the 'hello-world' Lambda function with an empty payload", markdown=True)
    export GIPHY_API_KEY=***
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.giphy import GiphyTools
    
    
    gif_agent = Agent(
        name="Gif Generator Agent",
        model=OpenAIChat(id="gpt-4o"),
        tools=[GiphyTools()],
        description="You are an AI agent that can generate gifs using Giphy.",
    )
    
    gif_agent.print_response("I want a gif to send to a friend for their birthday.")
    ​Toolkit Params
    Name
    Type
    Default
    Description

    base_dir

    Path

    -

    Specifies the base directory path for file operations.

    save_files

    bool

    True

    Determines whether files should be saved during the operation.

    read_files

    bool

    True

    ​Toolkit Functions

    Name
    Description

    save_file

    Saves the contents to a file called file_name and returns the file name if successful.

    read_file

    Reads the contents of the file file_name and returns the contents if successful.

    list_files

    Returns a list of files in the base directory

    ​
    ​Example

    The following agent will use Jina API to summarize the content of https://github.com/phidatahq

    cookbook/tools/jinareader_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    -

    The API key for authentication purposes, retrieved from the configuration.

    base_url

    str

    -

    The base URL of the API, retrieved from the configuration.

    search_url

    str

    -

    ​Toolkit Functions

    Function
    Description

    read_url

    Reads the content of a specified URL using Jina Reader API. Parameters include url for the URL to read. Returns the truncated content or an error message if the request fails.

    search_query

    Performs a web search using Jina Reader API based on a specified query. Parameters include query for the search term. Returns the truncated search results or an error message if the request fails.

    ​
    ​Example

    Use Nvidia with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "nvidia/llama-3.1-nemotron-70b-instruct"

    The specific model ID used for generating responses.

    name

    str

    "Nvidia"

    The name identifier for the Nvidia agent.

    provider

    str

    -

    Nvidia also supports the params of OpenAI.

    from Nvidia here
    ​Example

    Use Fireworks with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "accounts/fireworks/models/firefunction-v2"

    The specific model ID used for generating responses.

    name

    str

    "Fireworks: {id}"

    The name identifier for the agent. Defaults to "Fireworks: " followed by the model ID.

    provider

    str

    "Fireworks"

    Fireworks also supports the params of OpenAI.

    ​
    here

    Introduction

    Build humans and workflows to automate intelligent work.Build

    What is Bitca?

    Bitca is a framework for building multi-modal humansand workflows.

    • Build humanswith memory, knowledge, tools and reasoning.

    • Build teams of humans that can work together to solve problems.

    • Interact with your humansand workflows using a beautiful Human UI.

    Key Features

    • Simple & Elegant

    • Powerful & Flexible

    • Multi-Modal by default

    • Multi-Human orchestration

    Install

    Simple & Elegant

    Bitca Humans are simple and elegant, resulting in minimal, beautiful code.

    For example, you can create a web search human in 10 lines of code.

    Setup

    1

    Setup your virtual environment

    MacWindows

    2

    Install libraries

    MacWindows

    3

    Export your OpenAI key

    Bitca works with most model providers but for these examples let’s use OpenAI.

    MacWindows

    You can get an API key from .

    4

    Run the human

    Powerful & Flexible

    Bitca humans can use multiple tools and follow instructions to achieve complex tasks.

    For example, you can create a finance human with tools to query financial data.

    1

    Create a finance human

    finance_human.py

    2

    Run the human

    Install libraries

    Run the human

    Multi-Modal by default

    Bitca humans support text, images, audio and video.

    For example, you can create an image human that can understand images and make tool calls as needed

    1

    Create an image human

    image_human.py

    2

    Run the human

    Multi-Human orchestration

    Bitca humans can work together as a team to achieve complex tasks.

    1

    Create an human team

    human_team.py

    2

    Run the human team

    Run the human team

    Continue reading

    • Chat with your Humans using a beautiful Human UI.

    DeepSeek

    DeepSeek is a platform for providing endpoints for Large Language models.

    ​Authentication

    Set your DEEPSEEK_API_KEY environment variable. Get your key from here.

    MacWindows

    Example

    Use DeepSeek with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    DeepSeek also supports the params of .

    xAI

    xAI is a platform for providing endpoints for Large Language models.

    ​Authentication

    Set your XAI_API_KEY environment variable. You can get one from xAI here.

    MacWindows

    Example

    Use xAI with your Agent:

    agent.py

    Params

    For more information, please refer to the as well.

    Params

    Parameter
    Type
    Default
    Description

    xAI also supports the params of .

    Dalle

    Prerequisites

    You need to install the openai library.

    Set the OPENAI_API_KEY environment variable.

    Example

    The following agent will use DALL-E to generate an image based on a text prompt.

    cookbook/tools/dalle_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    OpenRouter

    OpenRouter is a platform for providing endpoints for Large Language models.

    ​Authentication

    Set your OPENROUTER_API_KEY environment variable. Get your key from here.

    MacWindows

    Example

    Use OpenRouter with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    OpenRouter also supports the params of .

    Fal

    FalTools enable an Agent to perform media generation tasks.

    ​Prerequisites

    The following example requires the fal_client library and an API key which can be obtained from Fal.

    Example

    The following agent will use FAL to generate any video requested by the user.

    cookbook/tools/fal_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    BaiduSearch

    BaiduSearch enables an Agent to search the web for information using the Baidu search engine.

    ​Prerequisites

    The following example requires the baidusearch library. To install BaiduSearch, run the following command:

    Example

    cookbook/tools/baidusearch_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Information

    • View on

    Jira

    JiraTools enable an Agent to perform Jira tasks.

    ​Prerequisites

    The following example requires the jira library and auth credentials.

    Example

    The following agent will use Jira API to search for issues in a project.

    cookbook/tools/jira_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Exa

    ExaTools enable an Agent to search the web using Exa.

    ​Prerequisites

    The following examples requires the exa-client library and an API key which can be obtained from Exa.

    Example

    The following agent will run seach exa for AAPL news and print the response.

    cookbook/tools/exa_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    DuckDuckGo

    DuckDuckGo enables an Agent to search the web for information.

    ​Prerequisites

    The following example requires the duckduckgo-search library. To install DuckDuckGo, run the following command:

    Example

    cookbook/tools/duckduckgo.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Arxiv

    ArxivTools enable an Agent to search for publications on Arxiv.

    ​Prerequisites

    The following example requires the arxiv and pypdf libraries.

    Example

    The following agent will run seach arXiv for “language models” and print the response.

    cookbook/tools/arxiv_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Information

    • View on

    Sambanova

    Sambanova is a platform for providing endpoints for Large Language models. Note that Sambanova currently does not support function calling.

    ​Authentication

    Set your SAMBANOVA_API_KEY environment variable. Get your key from here.

    MacWindows

    Example

    Use Sambanova with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Sambanova also supports the params of .

    Composio

    ComposioTools enable an Agent to work with tools like Gmail, Salesforce, Github, etc.

    ​Prerequisites

    The following example requires the composio-phidata library.

    Example

    The following agent will use Github Tool from Composio Toolkit to star a repo.

    cookbook/tools/composio_tools.py

    Toolkit Params

    The following parameters are used when calling the GitHub star repository action:

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Composio Toolkit provides 1000+ functions to connect to different software tools. Open this to view the complete list of functions.

    Email

    EmailTools enable an Agent to send an email to a user. The Agent can send an email to a user with a specific subject and body.

    ​Example

    cookbook/tools/email_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Calculator

    Calculator enables an Agent to perform mathematical calculations.

    Example

    The following agent will calculate the result of 10*5 and then raise it to the power of 2:

    cookbook/tools/calculator_tools.py

    Airflow

    Example

    The following agent will use Airflow to save and read a DAG file.

    cookbook/tools/airflow_tools.py

    Toolkit Params

    Gemini

    Use Google’s AI Studio to access the Gemini and Gemma models.

    Authentication

    Set your GOOGLE_API_KEY environment variable. You can get one .

    MacWindows

    Cal.com

    Prerequisites

    The following example requires the pytz and requests libraries.

    Firecrawl

    FirecrawlTools enable an Agent to perform web crawling and scraping tasks.

    Prerequisites

    The following example requires the firecrawl-py library and an API key which can be obtained from .

    Lumalabs

    LumaLabTools enables an Agent to generate media using the .

    Prerequisites

    The following example requires the lumaai library. To install the Lumalabs client, run the following command:

    ModelsLabs

    Prerequisites

    You need to install the requests library.

    Set the MODELS_LAB_API_KEY environment variable.

    Google Search

    GoogleSearch enables an Agent to perform web crawling and scraping tasks.

    Prerequisites

    The following examples requires the googlesearch and pycountry libraries.

    Apify

    ApifyTools enable an Agent to access the Apify API and run actors.

    Prerequisites

    The following example requires the apify-client library and an API token which can be obtained from .

    Resend

    ResendTools enable an Agent to send emails using Resend

    Prerequisites

    The following example requires the resend library and an API key from .

    Serpapi

    SerpApiTools enable an Agent to search Google and YouTube for a query.

    Prerequisites

    The following example requires the google-search-results library and an API key from .

    from bitca.agent import Agent
    from bitca.tools.file import FileTools
    
    agent = Agent(tools=[FileTools()], show_tool_calls=True)
    agent.print_response("What is the most advanced LLM currently? Save the answer to a file.", markdown=True)
    pip install -U jina
    from bitca.agent import Agent
    from bitca.tools.jina_tools import JinaReaderTools
    
    agent = Agent(tools=[JinaReaderTools()])
    agent.print_response("Summarize: https://github.com/bitca")
    export NVIDIA_API_KEY=***
    from bitca.agent import Agent, RunResponse
    from bitca.model.nvidia import Nvidia
    
    agent = Agent(model=Nvidia(), markdown=True)
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story")
    
    export FIREWORKS_API_KEY=***
    from bitca.agent import Agent, RunResponse
    from bitca.model.fireworks import Fireworks
    
    agent = Agent(
        model=Fireworks(id="accounts/fireworks/models/firefunction-v2"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    export DEEPSEEK_API_KEY=***
    export XAI_API_KEY=sk-***
    pip install openai
    export OPENAI_API_KEY=****
    export OPENROUTER_API_KEY=***
    pip install -U fal_client
    export FAL_KEY=***
    pip install -U baidusearch
    pip install -U jira
    export JIRA_SERVER_URL="YOUR_JIRA_SERVER_URL"
    export JIRA_USERNAME="YOUR_USERNAME"
    export JIRA_API_TOKEN="YOUR_API_TOKEN"
    pip install -U exa-client
    export EXA_API_KEY=***
    pip install -U duckduckgo-search
    pip install -U arxiv pypdf
    export SAMBANOVA_API_KEY=***
    pip install composio-phidata
    composio add github # Login into Github
    from bitca.agent import Agent
    from bitca.tools.email import EmailTools
    
    receiver_email = "<receiver_email>"
    sender_email = "<sender_email>"
    sender_name = "<sender_name>"
    sender_passkey = "<sender_passkey>"
    
    agent = Agent(
        tools=[
            EmailTools(
                receiver_email=receiver_email,
                sender_email=sender_email,
                sender_name=sender_name,
                sender_passkey=sender_passkey,
            )
        ]
    )
    agent.print_response("send an email to <receiver_email>")

    Allows reading from files during the operation.

    list_files

    bool

    True

    Enables listing of files in the specified directory.

    The URL used for search queries, retrieved from the configuration.

    max_content_length

    int

    -

    The maximum length of content allowed, retrieved from the configuration.

    The provider of the model, combining "Nvidia" with the model ID.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the Nvidia service. Retrieved from the environment variable NVIDIA_API_KEY.

    base_url

    str

    "https://integrate.api.nvidia.com/v1"

    The base URL for making API requests to the Nvidia service.

    The provider of the model.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the service. Retrieved from the environment variable FIREWORKS_API_KEY.

    base_url

    str

    "https://api.fireworks.ai/inference/v1"

    The base URL for making API requests to the Fireworks service.

    sender_passkey

    str

    -

    The passkey for the sender’s email.

    receiver_email

    str

    -

    The email address of the receiver.

    sender_name

    str

    -

    The name of the sender.

    sender_email

    str

    -

    email_user

    Emails the user with the given subject and body. Currently works with Gmail.

    ​
    ​

    The email address of the sender.

    A beautiful Human UI to chat with your humans
  • Humans RAG built-in

  • Structured outputs

  • Reasoning built-in

  • Monitoring & Debugging built-in

  • here
    ​
    ​
    ​
    ​
    More examples
    Monitoring & Debugging

    api_key

    Optional[str]

    -

    The API key used for authenticating requests to the DeepSeek service. Retrieved from the environment variable DEEPSEEK_API_KEY.

    base_url

    str

    "https://api.deepseek.com"

    The base URL for making API requests to the DeepSeek service.

    id

    str

    "deepseek-chat"

    The specific model ID used for generating responses.

    name

    str

    "DeepSeekChat"

    The name identifier for the DeepSeek model.

    provider

    str

    "DeepSeek"

    ​
    ​
    OpenAI

    The provider of the model.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the xAI service. Retrieved from the environment variable XAI_API_KEY.

    base_url

    str

    "https://api.xai.xyz/v1"

    The base URL for making API requests to the xAI service.

    id

    str

    "grok-beta"

    The specific model ID used for generating responses.

    name

    str

    "xAI"

    The name identifier for the xAI agent.

    provider

    str

    "xAI"

    ​
    ​
    xAI docs
    ​
    OpenAI

    The provider of the model, combining "xAI" with the model ID.

    quality

    str

    "standard"

    Image quality (standard or hd)

    style

    str

    "vivid"

    Image style (vivid or natural)

    api_key

    str

    None

    The OpenAI API key for authentication

    model

    str

    "dall-e-3"

    The DALL-E model to use

    n

    int

    1

    Number of images to generate

    size

    str

    "1024x1024"

    generate_image

    Generates an image based on a text prompt

    ​
    ​
    ​

    Image size (256x256, 512x512, 1024x1024, 1792x1024, or 1024x1792)

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the OpenRouter service. Retrieved from the environment variable OPENROUTER_API_KEY.

    base_url

    str

    "https://openrouter.ai/api/v1"

    The base URL for making API requests to the OpenRouter service.

    max_tokens

    int

    1024

    The maximum number of tokens to generate in the response.

    id

    str

    "gpt-4o"

    The specific model ID used for generating responses.

    name

    str

    "OpenRouter"

    The name identifier for the OpenRouter agent.

    provider

    str

    -

    ​
    ​
    OpenAI

    The provider of the model, combining "OpenRouter" with the model ID.

    api_key

    str

    None

    API key for authentication purposes.

    model

    str

    None

    The model to use for the media generation.

    generate_media

    Generate either images or videos depending on the user prompt.

    image_to_image

    Transform an input image based on a text prompt.

    ​
    ​
    ​

    proxy

    str

    -

    Specifies a single proxy address as a string to be used for the HTTP requests.

    timeout

    int

    10

    Sets the timeout for HTTP requests, in seconds.

    fixed_max_results

    int

    -

    Sets a fixed number of maximum results to return. No default is provided, must be specified if used.

    fixed_language

    str

    -

    Set the fixed language for the results.

    headers

    Any

    -

    baidu_search

    Use this function to search Baidu for a query.

    ​
    ​
    ​
    ​
    Github

    Headers to be used in the search request.

    token

    str

    None

    The JIRA API token for authentication, retrieved from the environment variable JIRA_TOKEN. Default is None if not set.

    server_url

    str

    ""

    The URL of the JIRA server, retrieved from the environment variable JIRA_SERVER_URL. Default is an empty string if not set.

    username

    str

    None

    The JIRA username for authentication, retrieved from the environment variable JIRA_USERNAME. Default is None if not set.

    password

    str

    None

    get_issue

    Retrieves issue details from JIRA. Parameters include: - issue_key: the key of the issue to retrieve Returns a JSON string containing issue details or an error message.

    create_issue

    Creates a new issue in JIRA. Parameters include: - project_key: the project in which to create the issue - summary: the issue summary - description: the issue description - issuetype: the type of issue (default is “Task”) Returns a JSON string with the new issue’s key and URL or an error message.

    search_issues

    Searches for issues using a JQL query in JIRA. Parameters include: - jql_str: the JQL query string - max_results: the maximum number of results to return (default is 50) Returns a JSON string containing a list of dictionaries with issue details or an error message.

    add_comment

    Adds a comment to an issue in JIRA. Parameters include: - issue_key: the key of the issue - comment: the comment text Returns a JSON string indicating success or an error message.

    ​
    ​
    ​

    The JIRA password for authentication, retrieved from the environment variable JIRA_PASSWORD. Default is None if not set.

    show_results

    bool

    False

    Controls whether to display search results directly.

    api_key

    str

    -

    API key for authentication purposes.

    search

    bool

    False

    Determines whether to enable search functionality.

    search_with_contents

    bool

    True

    search_exa

    Searches Exa for a query.

    search_exa_with_contents

    Searches Exa for a query and returns the contents from the search results.

    ​
    ​
    ​

    Indicates whether to include contents in the search results.

    headers

    Any

    -

    Accepts any type of header values to be sent with HTTP requests.

    proxy

    str

    -

    Specifies a single proxy address as a string to be used for the HTTP requests.

    proxies

    Any

    -

    Accepts a dictionary of proxies to be used for HTTP requests.

    timeout

    int

    10

    Sets the timeout for HTTP requests, in seconds.

    search

    bool

    True

    Enables the use of the duckduckgo_search function to search DuckDuckGo for a query.

    news

    bool

    True

    Enables the use of the duckduckgo_news function to fetch the latest news via DuckDuckGo.

    fixed_max_results

    int

    -

    duckduckgo_search

    Use this function to search DuckDuckGo for a query.

    duckduckgo_news

    Use this function to get the latest news from DuckDuckGo.

    ​
    ​
    ​

    Sets a fixed number of maximum results to return. No default is provided, must be specified if used.

    search_arxiv

    bool

    True

    Enables the functionality to search the arXiv database.

    read_arxiv_papers

    bool

    True

    Allows reading of arXiv papers directly.

    download_dir

    Path

    -

    search_arxiv_and_update_knowledge_base

    This function searches arXiv for a topic, adds the results to the knowledge base and returns them.

    search_arxiv

    Searches arXiv for a query.

    ​
    ​
    ​
    ​
    Github

    Specifies the directory path where downloaded files will be saved.

    api_key

    Optional[str]

    None

    The API key for authenticating with Sambanova (defaults to environment variable SAMBANOVA_API_KEY)

    base_url

    str

    "https://api.sambanova.ai/v1"

    The base URL for API requests

    id

    str

    "Meta-Llama-3.1-8B-Instruct"

    The id of the Sambanova model to use

    name

    str

    "Sambanova"

    The name of this chat model instance

    provider

    str

    "Sambanova"

    ​
    ​
    OpenAI

    The provider of the model

    owner

    str

    -

    The owner of the repository to star.

    repo

    str

    -

    The name of the repository to star.

    ​
    ​
    ​
    link
    ​Example

    The following agent will use Lumalabs to generate any video requested by the user.

    cookbook/tools/lumalabs_tool.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    None

    If you want to manually supply the Lumalabs API key.

    ​Toolkit Functions

    Function
    Description

    generate_video

    Generate a video from a prompt.

    image_to_video

    Generate a video from a prompt, a starting image and an ending image.

    Lumalabs platform
    ​
    ​Example

    The following agent will send an email using Resend

    cookbook/tools/resend_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    -

    API key for authentication purposes.

    from_email

    str

    -

    The email address used as the sender in email communications.

    ​Toolkit Functions

    Function
    Description

    send_email

    Send an email using the Resend API.

    ​
    Resend
    ​Example

    The following agent will search Google for the query: “Whats happening in the USA” and share results.

    cookbook/tools/serpapi_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    -

    API key for authentication purposes.

    search_youtube

    bool

    False

    Enables the functionality to search for content on YouTube.

    ​Toolkit Functions

    Function
    Description

    search_google

    This function searches Google for a query.

    search_youtube

    Searches YouTube for a query.

    ​
    SerpApi
    // pip install -U bitca
    python3 -m venv aienv
    aienv/scripts/activate
    pip install -U bitca openai duckduckgo-search
    setx OPENAI_API_KEY sk-***
    python web_search.py
    from bitca.human import Humans 
    from bitca.model.openai import OpenAIChat
    from bitca.tools.yfinance import YFinanceTools
    
    finance_human = Human(
        name="Finance Agent",
        model=OpenAIChat(id="gpt-4o"),
        tools=[YFinanceTools(stock_price=True, analyst_recommendations=True, company_info=True, company_news=True)],
        instructions=["Use tables to display data"],
        show_tool_calls=True,
        markdown=True,
    )
    finance_human.print_response("Summarize analyst recommendations for NVDA", stream=True)
    pip install yfinance
    python finance_human.py
    from bitca.human import Human
    from bitca.model.openai import OpenAIChat
    from bitca.tools.duckduckgo import DuckDuckGo
    
    human= Human(
        model=OpenAIChat(id="gpt-4o"),
        tools=[DuckDuckGo()],
        markdown=True,
    )
    
    human.print_response(
        "Tell me about this image and give me the latest news about it.",
        images=["https://upload.wikimedia.org/wikipedia/commons/b/bf/Krakow_-_Kosciol_Mariacki.jpg"],
        stream=True,
    )
    python image_human.py
    from bitca.human import Human
    from bitca.model.openai import OpenAIChat
    from bitca.tools.duckduckgo import DuckDuckGo
    from bitca.tools.yfinance import YFinanceTools
    
    web_human = Human(
        name="Web Human",
        role="Search the web for information",
        model=OpenAIChat(id="gpt-4o"),
        tools=[DuckDuckGo()],
        instructions=["Always include sources"],
        show_tool_calls=True,
        markdown=True,
    )
    
    finance_human = Human(
        name="Finance Human",
        role="Get financial data",
        model=OpenAIChat(id="gpt-4o"),
        tools=[YFinanceTools(stock_price=True, analyst_recommendations=True, company_info=True)],
        instructions=["Use tables to display data"],
        show_tool_calls=True,
        markdown=True,
    )
    
    human_team = Human(
        team=[web_human, finance_human],
        instructions=["Always include sources", "Use tables to display data"],
        show_tool_calls=True,
        markdown=True,
    )
    
    human_team.print_response("Summarize analyst recommendations and share the latest news for NVDA", stream=True)
    python human_team.py
    from bitca.agent import Agent, RunResponse
    from bitca.model.deepseek import DeepSeekChat
    
    agent = Agent(model=DeepSeekChat(), markdown=True)
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    
    from bitca.agent import Agent, RunResponse
    from bitca.model.xai import xAI
    
    agent = Agent(
        model=xAI(id="grok-beta"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    from bitca.agent import Agent
    from bitca.tools.dalle import Dalle
    
    # Create an Agent with the DALL-E tool
    agent = Agent(tools=[Dalle()], name="DALL-E Image Generator")
    
    # Example 1: Generate a basic image with default settings
    agent.print_response("Generate an image of a futuristic city with flying cars and tall skyscrapers", markdown=True)
    
    # Example 2: Generate an image with custom settings
    custom_dalle = Dalle(model="dall-e-3", size="1792x1024", quality="hd", style="natural")
    
    agent_custom = Agent(
        tools=[custom_dalle],
        name="Custom DALL-E Generator",
        show_tool_calls=True,
    )
    
    agent_custom.print_response("Create a panoramic nature scene showing a peaceful mountain lake at sunset", markdown=True)
    from bitca.agent import Agent, RunResponse
    from bitca.model.openrouter import OpenRouter
    
    agent = Agent(
        model=OpenRouter(id="gpt-4o"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.fal_tools import FalTools
    
    fal_agent = Agent(
        name="Fal Video Generator Agent",
        model=OpenAIChat(id="gpt-4o"),
        tools=[FalTools("fal-ai/hunyuan-video")],
        description="You are an AI agent that can generate videos using the Fal API.",
        instructions=[
            "When the user asks you to create a video, use the `generate_media` tool to create the video.",
            "Return the URL as raw to the user.",
            "Don't convert video URL to markdown or anything else.",
        ],
        markdown=True,
        debug_mode=True,
        show_tool_calls=True,
    )
    
    fal_agent.print_response("Generate video of balloon in the ocean")
    from bitca.agent import Agent
    from bitca.tools.baidusearch import BaiduSearch
    
    agent = Agent(
        tools=[BaiduSearch()],
        description="You are a search agent that helps users find the most relevant information using Baidu.",
        instructions=[
            "Given a topic by the user, respond with the 3 most relevant search results about that topic.",
            "Search for 5 results and select the top 3 unique items.",
            "Search in both English and Chinese.",
        ],
        show_tool_calls=True,
    )
    agent.print_response("What are the latest advancements in AI?", markdown=True)
    from bitca.agent import Agent
    from bitca.tools.jira_tools import JiraTools
    
    agent = Agent(tools=[JiraTools()])
    agent.print_response("Find all issues in project PROJ", markdown=True)
    from bitca.agent import Agent
    from bitca.tools.exa import ExaTools
    
    agent = Agent(tools=[ExaTools(include_domains=["cnbc.com", "reuters.com", "bloomberg.com"])], show_tool_calls=True)
    agent.print_response("Search for AAPL news", markdown=True)
    from bitca.agent import Agent
    from bitca.tools.duckduckgo import DuckDuckGo
    
    agent = Agent(tools=[DuckDuckGo()], show_tool_calls=True)
    agent.print_response("Whats happening in France?", markdown=True)
    from bitca.agent import Agent
    from bitca.tools.arxiv_toolkit import ArxivToolkit
    
    agent = Agent(tools=[ArxivToolkit()], show_tool_calls=True)
    agent.print_response("Search arxiv for 'language models'", markdown=True)
    from bitca.agent import Agent, RunResponse
    from bitca.model.sambanova import Sambanova
    
    agent = Agent(model=Sambanova(), markdown=True)
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    from phi.agent import Agent
    from composio_phidata import Action, ComposioToolSet
    
    
    toolset = ComposioToolSet()
    composio_tools = toolset.get_tools(
      actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER]
    )
    
    agent = Agent(tools=composio_tools, show_tool_calls=True)
    agent.print_response("Can you star phidatahq/phidata repo?")
    export LUMAAI_API_KEY=***
    pip install -U lumaai
    from bitca.agent import Agent
    from bitca.llm.openai import OpenAIChat
    from bitca.tools.lumalab import LumaLabTools
    
    luma_agent = Agent(
        name="Luma Video Agent",
        llm=OpenAIChat(model="gpt-4o"),
        tools=[LumaLabTools()],  # Using the LumaLab tool we created
        markdown=True,
        debug_mode=True,
        show_tool_calls=True,
        instructions=[
            "You are an agent designed to generate videos using the Luma AI API.",
            "You can generate videos in two ways:",
            "1. Text-to-Video Generation:",
            "2. Image-to-Video Generation:",
            "Choose the appropriate function based on whether the user provides image URLs or just a text prompt.",
            "The video will be displayed in the UI automatically below your response, so you don't need to show the video URL in your response.",
        ],
        system_message=(
            "Use generate_video for text-to-video requests and image_to_video for image-based "
            "generation. Don't modify default parameters unless specifically requested. "
            "Always provide clear feedback about the video generation status."
        ),
    )
    
    luma_agent.run("Generate a video of a car in a sky")
    pip install -U resend
    export RESEND_API_KEY=***
    from bitca.agent import Agent
    from bitca.tools.resend_tools import ResendTools
    
    from_email = "<enter_from_email>"
    to_email = "<enter_to_email>"
    
    agent = Agent(tools=[ResendTools(from_email=from_email)], show_tool_calls=True)
    agent.print_response(f"Send an email to {to_email} greeting them with hello world")
    pip install -U google-search-results
    export SERPAPI_API_KEY=***
    from bitca.agent import Agent
    from bitca.tools.serpapi_tools import SerpApiTools
    
    agent = Agent(tools=[SerpApiTools()])
    agent.print_response("Whats happening in the USA?", markdown=True)
    ​Toolkit Params
    Parameter
    Type
    Default
    Description

    add

    bool

    True

    Enables the functionality to perform addition.

    subtract

    bool

    True

    Enables the functionality to perform subtraction.

    multiply

    bool

    True

    ​Toolkit Functions

    Function
    Description

    add

    Adds two numbers and returns the result.

    subtract

    Subtracts the second number from the first and returns the result.

    multiply

    Multiplies two numbers and returns the result.

    divide

    Divides the first number by the second and returns the result. Handles division by zero.

    exponentiate

    Raises the first number to the power of the second number and returns the result.

    factorial

    Calculates the factorial of a number and returns the result. Handles negative numbers.

    ​
    Parameter
    Type
    Default
    Description

    dags_dir

    Path or str

    Path.cwd()

    Directory for DAG files

    save_dag

    bool

    True

    Whether to register the save_dag_file function

    read_dag

    bool

    True

    Whether to register the read_dag_file function

    ​Toolkit Functions

    Function
    Description

    save_dag_file

    Saves python code for an Airflow DAG to a file

    read_dag_file

    Reads an Airflow DAG file and returns the contents

    ​Information

    • View on Github

    ​
    ​Example

    Use Gemini with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "gemini-1.5-flash"

    The specific Gemini model ID to use.

    name

    str

    "Gemini"

    The name of this Gemini model instance.

    provider

    str

    "Google"

    ​
    from Google here
    ​Example

    The following agent will use Cal.com to list all events in your Cal.com account for tomorrow.

    cookbook/tools/calcom_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    None

    Cal.com API key

    event_type_id

    int

    None

    Event type ID for scheduling

    user_timezone

    str

    None

    ​Toolkit Functions

    Function
    Description

    get_available_slots

    Gets available time slots for a given date range

    create_booking

    Creates a new booking with provided details

    get_upcoming_bookings

    Gets list of upcoming bookings

    get_booking_details

    Gets details for a specific booking

    reschedule_booking

    Reschedules an existing booking

    cancel_booking

    Cancels an existing booking

    ​Example

    The following agent will scrape the content from https://finance.yahoo.com/ and return a summary of the content:

    cookbook/tools/firecrawl_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    None

    Optional API key for authentication purposes.

    formats

    List[str]

    None

    Optional list of formats to be used for the operation.

    limit

    int

    10

    ​Toolkit Functions

    Function
    Description

    scrape_website

    Scrapes a website using Firecrawl. Parameters include url to specify the URL to scrape. The function supports optional formats if specified. Returns the results of the scraping in JSON format.

    crawl_website

    Crawls a website using Firecrawl. Parameters include url to specify the URL to crawl, and an optional limit to define the maximum number of pages to crawl. The function supports optional formats and returns the crawling results in JSON format.

    ​
    Firecrawl
    ​Example

    The following agent will use ModelsLabs to generate a video based on a text prompt.

    cookbook/tools/models_labs_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    None

    The ModelsLab API key for authentication

    url

    str

    "https://modelslab.com/api/v6/video/text2video"

    The API endpoint URL

    fetch_url

    str

    https://modelslab.com/api/v6/video/fetch

    ​Toolkit Functions

    Function
    Description

    generate_media

    Generates a video or gif based on a text prompt

    ​Example

    The following agent will search Google for the latest news about “Mistral AI”:

    cookbook/tools/googlesearch_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    fixed_max_results

    int

    None

    Optional fixed maximum number of results to return.

    fixed_language

    str

    None

    Optional fixed language for the requests.

    headers

    Any

    None

    ​Toolkit Functions

    Function
    Description

    google_search

    Searches Google for a specified query. Parameters include query for the search term, max_results for the maximum number of results (default is 5), and language for the language of the search results (default is “en”). Returns the search results as a JSON formatted string.

    ​
    ​Example

    The following agent will use Apify to crawl the webpage: https://docs.projectbit.ca/ and summarize it.

    cookbook/tools/apify_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    api_key

    str

    -

    API key for authentication purposes.

    website_content_crawler

    bool

    True

    Enables the functionality to crawl a website using website-content-crawler actor.

    web_scraper

    bool

    False

    ​Toolkit Functions

    Function
    Description

    website_content_crawler

    Crawls a website using Apify’s website-content-crawler actor.

    web_scrapper

    Scrapes a website using Apify’s web-scraper actor.

    ​Information

    • View on Github

    ​
    Apify

    Azure

    Use the best in class GPT models using Azure’s OpenAI API.

    ​Authentication

    Set your environment variables.

    MacWindows

    export AZURE_OPENAI_API_KEY=***
    export AZURE_OPENAI_ENDPOINT=***
    export AZURE_OPENAI_MODEL_NAME=***
    export AZURE_OPENAI_DEPLOYMENT=***
    # Optional:
    # export AZURE_OPENAI_API_VERSION=***

    Example

    Use AzureOpenAIChat with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Azure also supports the params of .

    Storage

    Agents use storage to persist sessions by storing them in a database.

    Agents come with built-in memory, but it only lasts while the session is active. To continue conversations across sessions, we store agent sessions in a database like PostgreSQL.

    The general syntax for adding storage to an Agent looks like:

    Example

    1

    Run Postgres

    Install docker desktop and run Postgres on port 5532 using:

    2

    Create an Agent with Storage

    Create a file agent_with_storage.py with the following contents

    3

    Run the agent

    Install libraries

    MacWindows

    Run the agent

    Now the agent continues across sessions. Ask a question:

    Then message bye to exit, start the app again and ask:

    4

    Start a new run

    Run the agent_with_storage.py file with the --new flag to start a new run.

    Params

    Parameter
    Type
    Default
    Description

    Anthropic Claude

    Claude is a family of foundational AI models by Anthropic that can be used in a variety of applications.

    ​Authentication

    Set your ANTHROPIC_API_KEY environment. You can get one from Anthropic here.

    MacWindows

    Example

    Use Claude with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Gemini - VertexAI

    ertexAI is Google’s cloud platform for building, training, and deploying machine learning models.

    ​Authentication

    Authenticate with Gcloud

    Example

    Use Gemini with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    AWS Bedrock Claude

    Use AWS Bedrock to access the Claude models.

    ​Authentication

    Set your AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION environment variables. Get your keys from here.

    MacWindows

    Example

    Use AWS BedrockClaude with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Together

    Together is a platform for providing endpoints for Large Language models.

    ​Authentication

    Set your TOGETHER_API_KEY environment variable. Get your key from Together here.

    MacWindows

    Example

    Use Together with your Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Together also supports the params of .

    Github

    GithubTools enables an Agent to access Github repositories and perform tasks such as listing open pull requests, issues and more.

    ​Prerequisites

    The following examples requires the PyGithub library and a Github access token which can be obtained from here.

    Example

    The following agent will search Google for the latest news about “Mistral AI”:

    cookbook/tools/github_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Linear

    LinearTool enable an Agent to perform Linear tasks.

    ​Prerequisites

    ​Example

    The following agent will use Linear API to search for issues in a project for a specific user.

    cookbook/tools/linear_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Ollama

    Run Large Language Models locally with Ollama

    Ollama is a fantastic tool for running models locally. Install ollama and run a model using

    run modelserve

    ollama run llama3.1

    After you have the local model running, use the Ollama model to access them

    ​Example

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Newspaper4k

    Newspaper4k enables an Agent to read news articles using the Newspaper4k library.

    ​Prerequisites

    The following example requires the newspaper4k and lxml_html_clean libraries.

    Example

    The following agent will summarize the article: .

    cookbook/tools/newspaper4k_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    OpenBB

    OpenBBTools enable an Agent to provide information about stocks and companies.

    cookbook/tools/openbb_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Replicate

    ReplicateTools enables an Agent to generate media using the Replicate platform.

    ​Prerequisites

    The following example requires the replicate library. To install the Replicate client, run the following command:

    Example

    The following agent will use Replicate to generate images or videos requested by the user.

    cookbook/tools/replicate_tool.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Spider

    SpiderTools is an open source web Scraper & Crawler that returns LLM-ready data. To start using Spider, you need an API key from the Spider dashboard.

    ​Prerequisites

    The following example requires the spider-client library.

    Example

    The following agent will run a search query to get the latest news in USA and scrape the first search result. The agent will return the scraped data in markdown format.

    cookbook/tools/spider_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Shell

    ShellTools enable an Agent to interact with the shell to run commands.

    ​Example

    The following agent will run a shell command and show contents of the current directory.

    Mention your OS to the agent to make sure it runs the correct command.

    cookbook/tools/shell_tools.py

    from bitca.agent import Agent
    from bitca.tools.shell import ShellTools
    
    agent = Agent(tools=[ShellTools()], show_tool_calls=True)
    agent.print_response("Show me the contents of the current directory", markdown=True)

    Functions in Toolkit

    Function
    Description

    Information

    • View on

    Pubmed

    PubmedTools enable an Agent to search for Pubmed for articles.

    ​Example

    The following agent will search Pubmed for articles related to “ulcerative colitis”.

    cookbook/tools/pubmed.py

    from bitca.agent import Agent
    from bitca.tools.pubmed import PubmedTools
    
    agent = Agent(tools=[PubmedTools()], show_tool_calls=True)
    agent.print_response("Tell me about ulcerative colitis.")

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Sleep

    Example

    The following agent will use the sleep tool to pause execution for a given number of seconds.

    cookbook/tools/sleep_tools.py

    from bitca.agent import Agent
    from bitca.tools.sleep import Sleep
    
    # Create an Agent with the Sleep tool
    agent = Agent(tools=[Sleep()], name="Sleep Agent")
    
    # Example 1: Sleep for 2 seconds
    agent.print_response("Sleep for 2 seconds")
    
    # Example 2: Sleep for a longer duration
    agent.print_response("Sleep for 5 seconds")

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Website

    WebsiteTools enable an Agent to parse a website and add its contents to the knowledge base.

    ​Prerequisites

    The following example requires the beautifulsoup4 library.

    Example

    The following agent will read the contents of a website and add it to the knowledge base.

    cookbook/tools/website_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Knowledges

    In addition to the default Markdown you can write, GitBook has a number of out-of-the-box interactive blocks you can use. You can find interactive blocks by pressing / from within the editor.

    Tabs

    Each tab is like a mini page — it can contain multiple other blocks, of any type. So you can add code blocks, images, integration blocks and more to individual tabs in the same tab block.

    Add images, embedded content, code blocks, and more.

    Expandable sections

    Click me to expand

    Expandable blocks are helpful in condensing what could otherwise be a lengthy paragraph. They are also great in step-by-step guides and FAQs.

    Drawings

    Embedded content

    GitBook supports thousands of embedded websites out-of-the-box, simply by pasting their links. Feel free to check out which ones.

    Tools

    Agents use tools to take actions and interact with external systems.

    Tools are functions that an Agent can run to achieve tasks. For example: searching the web, running SQL, sending an email or calling APIs. You can use any python function as a tool or use a pre-built toolkit. The general syntax is:

    Using a Toolkit

    Bitca provides many pre-built toolkits that you can add to your Agents. For example, let’s use the DuckDuckGo toolkit to search the web.

    1

    Cohere

    Leverage Cohere’s powerful command models and more.

    Authentication

    Set your CO_API_KEY environment variable. Get your key from .

    MacWindows

    CSV

    CsvTools enable an Agent to read and write CSV files.

    Example

    The following agent will download the IMDB csv file and allow the user to query it using a CLI app.

    cookbook/tools/csv_tools.py

    DuckDb

    DuckDbTools enable an Agent to run SQL and analyze data using DuckDb.

    Prerequisites

    The following example requires DuckDB library. To install DuckDB, run the following command:

    For more installation options, please refer to .

    Yfinance

    YouTubeTools enable an Agent to access captions and metadata of YouTube videos, when provided with a video URL.

    Prerequisites

    The following example requires the youtube_transcript_api library.

    from bitca.agent import Agent
    from bitca.tools.calculator import Calculator
    
    agent = Agent(
        tools=[
            Calculator(
                add=True,
                subtract=True,
                multiply=True,
                divide=True,
                exponentiate=True,
                factorial=True,
                is_prime=True,
                square_root=True,
            )
        ],
        show_tool_calls=True,
        markdown=True,
    )
    agent.print_response("What is 10*5 then to the power of 2, do it step by step")
    from bitca.agent import Agent
    from bitca.tools.airflow import AirflowToolkit
    
    agent = Agent(
        tools=[AirflowToolkit(dags_dir="dags", save_dag=True, read_dag=True)], show_tool_calls=True, markdown=True
    )
    
    
    dag_content = """
    from airflow import DAG
    from airflow.operators.python import PythonOperator
    from datetime import datetime, timedelta
    default_args = {
        'owner': 'airflow',
        'depends_on_past': False,
        'start_date': datetime(2024, 1, 1),
        'email_on_failure': False,
        'email_on_retry': False,
        'retries': 1,
        'retry_delay': timedelta(minutes=5),
    }
    # Using 'schedule' instead of deprecated 'schedule_interval'
    with DAG(
        'example_dag',
        default_args=default_args,
        description='A simple example DAG',
        schedule='@daily',  # Changed from schedule_interval
        catchup=False
    ) as dag:
        def print_hello():
            print("Hello from Airflow!")
            return "Hello task completed"
        task = PythonOperator(
            task_id='hello_task',
            python_callable=print_hello,
            dag=dag,
        )
    """
    
    agent.run(f"Save this DAG file as 'example_dag.py': {dag_content}")
    
    
    agent.print_response("Read the contents of 'example_dag.py'")
    export GOOGLE_API_KEY=***
    
    from bitca.agent import Agent, RunResponse
    from bitca.model.google import Gemini
    
    agent = Agent(
        model=Gemini(id="gemini-1.5-flash"),
        markdown=True,
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    pip install requests pytz
    export CALCOM_API_KEY="your_api_key"
    export CALCOM_EVENT_TYPE_ID="your_event_type_id"
    
    agent = Agent(
        name="Calendar Assistant",
        instructions=[
            f"You're scheduing assistant. Today is {datetime.now()}.",
            "You can help users by:",
            "- Finding available time slots",
            "- Creating new bookings",
            "- Managing existing bookings (view, reschedule, cancel) ",
            "- Getting booking details",
            "- IMPORTANT: In case of rescheduling or cancelling booking, call the get_upcoming_bookings function to get the booking uid. check available slots before making a booking for given time",
            "Always confirm important details before making bookings or changes.",
        ],
        model=OpenAIChat(id="gpt-4"),
        tools=[CalCom(user_timezone="America/New_York")],
        show_tool_calls=True,
        markdown=True,
    )
    
    agent.print_response("What are my bookings for tomorrow?")
    pip install -U firecrawl-py
    export FIRECRAWL_API_KEY=***
    from bitca.agent import Agent
    from bitca.tools.firecrawl import FirecrawlTools
    
    agent = Agent(tools=[FirecrawlTools(scrape=False, crawl=True)], show_tool_calls=True, markdown=True)
    agent.print_response("Summarize this https://finance.yahoo.com/")
    pip install requests
    export MODELS_LAB_API_KEY=****
    from bitca.agent import Agent
    from bitca.tools.models_labs import ModelsLabs
    
    # Create an Agent with the ModelsLabs tool
    agent = Agent(tools=[ModelsLabs()], name="ModelsLabs Agent")
    
    agent.print_response("Generate a video of a beautiful sunset over the ocean", markdown=True)
    pip install -U googlesearch-python pycountry
    from bitca.agent import Agent
    from bitca.tools.googlesearch import GoogleSearch
    
    agent = Agent(
        tools=[GoogleSearch()],
        description="You are a news agent that helps users find the latest news.",
        instructions=[
            "Given a topic by the user, respond with 4 latest news items about that topic.",
            "Search for 10 news items and select the top 4 unique items.",
            "Search in English and in French.",
        ],
        show_tool_calls=True,
        debug_mode=True,
    )
    agent.print_response("Mistral AI", markdown=True)
    pip install -U apify-client
    export MY_APIFY_TOKEN=***
    from bitca.agent import Agent
    from bitca.tools.apify import ApifyTools
    
    agent = Agent(tools=[ApifyTools()], show_tool_calls=True)
    agent.print_response("Tell me about https://docs.bitca.com/introduction", markdown=True)
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.duckduckgo import DuckDuckGo
    from bitca.storage.agent.postgres import PgAgentStorage
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        storage=PgAgentStorage(table_name="agent_sessions", db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
        tools=[DuckDuckGo()],
        show_tool_calls=True,
        add_history_to_messages=True,
    )
    agent.print_response("How many people live in Canada?")
    agent.print_response("What is their national anthem called?")
    agent.print_response("Which country are we speaking about?")
    docker run -d \
      -e POSTGRES_DB=ai \
      -e POSTGRES_USER=ai \
      -e POSTGRES_PASSWORD=ai \
      -e PGDATA=/var/lib/postgresql/data/pgdata \
      -v pgvolume:/var/lib/postgresql/data \
      -p 5532:5432 \
      --name pgvector \
      bitca/pgvector:16
    export ANTHROPIC_API_KEY=***
    export AWS_ACCESS_KEY_ID=***
    export AWS_SECRET_ACCESS_KEY=***
    export AWS_DEFAULT_REGION=***
    export TOGETHER_API_KEY=***
    pip install -U PyGithub
    export GITHUB_ACCESS_TOKEN=***
    export LINEAR_API_KEY="LINEAR_API_KEY"
    from bitca.agent import Agent, RunResponse
    from bitca.model.ollama import Ollama
    
    agent = Agent(
        model=Ollama(id="llama3.1"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    pip install -U newspaper4k lxml_html_clean
    from bitca.agent import Agent
    from bitca.tools.openbb_tools import OpenBBTools
    
    
    agent = Agent(tools=[OpenBBTools()], debug_mode=True, show_tool_calls=True)
    
    # Example usage showing stock analysis
    agent.print_response(
        "Get me the current stock price and key information for Apple (AAPL)"
    )
    
    # Example showing market analysis
    agent.print_response(
        "What are the top gainers in the market today?"
    )
    
    # Example showing economic indicators
    agent.print_response(
        "Show me the latest GDP growth rate and inflation numbers for the US"
    )
    export REPLICATE_API_TOKEN=***
    pip install -U replicate
    pip install -U spider-client
    pip install -U beautifulsoup4

    Enables the functionality to perform multiplication.

    divide

    bool

    True

    Enables the functionality to perform division.

    exponentiate

    bool

    False

    Enables the functionality to perform exponentiation.

    factorial

    bool

    False

    Enables the functionality to calculate the factorial of a number.

    is_prime

    bool

    False

    Enables the functionality to check if a number is prime.

    square_root

    bool

    False

    Enables the functionality to calculate the square root of a number.

    is_prime

    Checks if a number is prime and returns the result.

    square_root

    Calculates the square root of a number and returns the result. Handles negative numbers.

    name

    str

    "AirflowTools"

    The name of the tool

    The provider of the model.

    function_declarations

    Optional[List[FunctionDeclaration]]

    None

    List of function declarations for the model.

    generation_config

    Optional[Any]

    None

    Configuration for text generation.

    safety_settings

    Optional[Any]

    None

    Safety settings for the model.

    generative_model_kwargs

    Optional[Dict[str, Any]]

    None

    Additional keyword arguments for the generative model.

    api_key

    Optional[str]

    None

    API key for authentication.

    client_params

    Optional[Dict[str, Any]]

    None

    Additional parameters for the client.

    client

    Optional[GenerativeModel]

    None

    The underlying generative model client.

    User’s timezone (e.g. “America/New_York”)

    get_available_slots

    bool

    True

    Enable getting available time slots

    create_booking

    bool

    True

    Enable creating new bookings

    get_upcoming_bookings

    bool

    True

    Enable getting upcoming bookings

    reschedule_booking

    bool

    True

    Enable rescheduling bookings

    cancel_booking

    bool

    True

    Enable canceling bookings

    Maximum number of items to retrieve. The default value is 10.

    scrape

    bool

    True

    Enables the scraping functionality. Default is True.

    crawl

    bool

    False

    Enables the crawling functionality. Default is False.

    The URL to fetch the video status from

    wait_for_completion

    bool

    False

    Whether to wait for the video to be ready

    add_to_eta

    int

    15

    Time to add to the ETA to account for the time it takes to fetch the video

    max_wait_time

    int

    60

    Maximum time to wait for the video to be ready

    file_type

    str

    "mp4"

    The type of file to generate

    Optional headers to include in the requests.

    proxy

    str

    None

    Optional proxy to be used for the requests.

    timeout

    int

    None

    Optional timeout for the requests, in seconds.

    Enables the functionality to crawl a website using web_scraper actor.

    read_article

    bool

    True

    Enables the functionality to read the full content of an article.

    include_summary

    bool

    False

    Specifies whether to include a summary of the article along with the full content.

    article_length

    int

    -

    The maximum length of the article or its summary to be processed or returned.

    get_stock_price

    This function gets the current stock price for a stock symbol or list of symbols.

    search_company_symbol

    This function searches for the stock symbol of a company.

    get_price_targets

    This function gets the price targets for a stock symbol or list of symbols.

    get_company_news

    This function gets the latest news for a stock symbol or list of symbols.

    get_company_profile

    This function gets the company profile for a stock symbol or list of symbols.

    ​

    run_shell_command

    Runs a shell command and returns the output or error.

    ​
    ​
    Github

    email

    str

    "[email protected]"

    Specifies the email address to use.

    max_results

    int

    None

    Optional parameter to specify the maximum number of results to return.

    search_pubmed

    Searches PubMed for articles based on a specified query. Parameters include query for the search term and max_results for the maximum number of results to return (default is 10). Returns a JSON string containing the search results, including publication date, title, and summary.

    ​
    ​

    name

    str

    "sleep"

    The name of the tool

    sleep

    Pauses execution for a specified number of seconds

    ​
    ​

    format

    Optional[str]

    None

    The format of the response.

    options

    Optional[Any]

    None

    Additional options to pass to the model.

    keep_alive

    Optional[Union[float, str]]

    None

    The keep alive time for the model.

    request_params

    Optional[Dict[str, Any]]

    None

    Additional parameters to pass to the request.

    host

    Optional[str]

    None

    The host to connect to.

    timeout

    Optional[Any]

    None

    The timeout for the connection.

    client_params

    Optional[Dict[str, Any]]

    None

    Additional parameters to pass to the client.

    client

    Optional[OllamaClient]

    None

    A pre-configured instance of the Ollama client.

    async_client

    Optional[AsyncOllamaClient]

    None

    A pre-configured instance of the asynchronous Ollama client.

    id

    str

    "llama3.2"

    The ID of the model to use.

    name

    str

    "Ollama"

    The name of the model.

    provider

    str

    "Ollama llama3.2"

    ​

    The provider of the model.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the Azure OpenAI service.

    api_version

    str

    "2024-02-01"

    The version of the Azure OpenAI API to use.

    azure_endpoint

    Optional[str]

    -

    The endpoint URL for the Azure OpenAI service.

    azure_deployment

    Optional[str]

    -

    The deployment name or ID in Azure.

    base_url

    Optional[str]

    -

    The base URL for making API requests to the Azure OpenAI service.

    azure_ad_token

    Optional[str]

    -

    The Azure Active Directory token for authenticating requests.

    azure_ad_token_provider

    Optional[Any]

    -

    The provider for obtaining Azure Active Directory tokens.

    organization

    Optional[str]

    -

    The organization associated with the API requests.

    openai_client

    Optional[AzureOpenAIClient]

    -

    An instance of AzureOpenAIClient provided for making API requests.

    id

    str

    -

    The specific model ID used for generating responses. This field is required.

    name

    str

    "AzureOpenAIChat"

    The name identifier for the agent.

    provider

    str

    "Azure"

    ​
    ​
    OpenAI

    The provider of the model.

    storage

    Optional[AgentStorage]

    None

    Storage mechanism for the agent, if applicable.

    max_tokens

    Optional[int]

    1024

    Maximum number of tokens to generate in the chat completion

    temperature

    Optional[float]

    None

    Controls randomness in the model's output

    stop_sequences

    Optional[List[str]]

    None

    A list of strings that the model should stop generating text at

    top_p

    Optional[float]

    None

    Controls diversity via nucleus sampling

    top_k

    Optional[int]

    None

    Controls diversity via top-k sampling

    request_params

    Optional[Dict[str, Any]]

    None

    Additional parameters to include in the request

    api_key

    Optional[str]

    None

    The API key for authenticating with Anthropic

    client_params

    Optional[Dict[str, Any]]

    None

    Additional parameters for client configuration

    client

    Optional[AnthropicClient]

    None

    A pre-configured instance of the Anthropic client

    id

    str

    "claude-3-5-sonnet-20240620"

    The id of the Anthropic Claude model to use

    name

    str

    "Claude"

    The name of the model

    provider

    str

    "Anthropic"

    ​
    ​

    The provider of the model

    max_tokens

    Optional[int]

    1024

    The maximum number of tokens to generate in the response.

    temperature

    Optional[float]

    -

    The sampling temperature to use, between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic.

    stop_sequences

    Optional[List[str]]

    -

    A list of sequences where the API will stop generating further tokens.

    top_p

    Optional[float]

    -

    Nucleus sampling parameter. The model considers the results of the tokens with top_p probability mass.

    top_k

    Optional[int]

    -

    The number of highest probability vocabulary tokens to keep for top-k-filtering.

    request_params

    Optional[Dict[str, Any]]

    -

    Additional parameters to include in the request.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the service.

    client_params

    Optional[Dict[str, Any]]

    -

    Additional parameters for client configuration.

    client

    Optional[AnthropicClient]

    -

    A pre-configured instance of the Anthropic client.

    id

    str

    "claude-3-5-sonnet-20240620"

    The specific model ID used for generating responses.

    name

    str

    "Claude"

    The name identifier for the agent.

    provider

    str

    "Anthropic"

    ​
    ​

    The provider of the model.

    max_tokens

    int

    4096

    The maximum number of tokens to generate in the response.

    temperature

    Optional[float]

    -

    The sampling temperature to use, between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic.

    top_p

    Optional[float]

    -

    The nucleus sampling parameter. The model considers the results of the tokens with top_p probability mass.

    top_k

    Optional[int]

    -

    The number of highest probability vocabulary tokens to keep for top-k-filtering.

    stop_sequences

    Optional[List[str]]

    -

    A list of sequences where the API will stop generating further tokens.

    anthropic_version

    str

    "bedrock-2023-05-31"

    The version of the Anthropic API to use.

    request_params

    Optional[Dict[str, Any]]

    -

    Additional parameters for the request, provided as a dictionary.

    client_params

    Optional[Dict[str, Any]]

    -

    Additional client parameters for initializing the AwsBedrock client, provided as a dictionary.

    id

    str

    "anthropic.claude-3-sonnet-20240229-v1:0"

    The specific model ID used for generating responses.

    name

    str

    "AwsBedrockAnthropicClaude"

    The name identifier for the Claude agent.

    provider

    str

    "AwsBedrock"

    ​
    ​

    The provider of the model.

    api_key

    Optional[str]

    None

    The API key to authorize requests to Together. Defaults to environment variable TOGETHER_API_KEY.

    base_url

    str

    "https://api.together.xyz/v1"

    The base URL for API requests.

    monkey_patch

    bool

    False

    Whether to apply monkey patching.

    id

    str

    "mistralai/Mixtral-8x7B-Instruct-v0.1"

    The id of the Together model to use.

    name

    str

    "Together"

    The name of this chat model instance.

    provider

    str

    "Together " + id

    ​
    ​
    OpenAI

    The provider of the model.

    list_repositories

    bool

    True

    Enable listing repositories for a user/organization.

    get_repository

    bool

    True

    Enable getting repository details.

    list_pull_requests

    bool

    True

    Enable listing pull requests for a repository.

    get_pull_request

    bool

    True

    Enable getting pull request details.

    get_pull_request_changes

    bool

    True

    Enable getting pull request file changes.

    create_issue

    bool

    True

    Enable creating issues in repositories.

    create_issue

    Creates a new issue in a repository.

    access_token

    str

    None

    Github access token for authentication. If not provided, will use GITHUB_ACCESS_TOKEN environment variable.

    base_url

    str

    None

    Optional base URL for Github Enterprise installations.

    search_repositories

    bool

    True

    search_repositories

    Searches Github repositories based on a query.

    list_repositories

    Lists repositories for a given user or organization.

    get_repository

    Gets details about a specific repository.

    list_pull_requests

    Lists pull requests for a repository.

    get_pull_request

    Gets details about a specific pull request.

    get_pull_request_changes

    Gets the file changes in a pull request.

    ​
    ​
    ​

    Enable searching Github repositories.

    update_issue

    bool

    True

    Enable update_issue tool.

    get_user_assigned_issues

    bool

    True

    Enable get_user_assigned_issues tool.

    get_workflow_issues

    bool

    True

    Enable get_workflow_issues tool.

    get_high_priority_issues

    bool

    True

    Enable get_high_priority_issues tool.

    get_high_priority_issues

    Retrieve issues with a high priority (priority <= 2).

    get_user_details

    bool

    True

    Enable get_user_details tool.

    get_issue_details

    bool

    True

    Enable get_issue_details tool.

    create_issue

    bool

    True

    get_user_details

    Fetch authenticated user details.

    get_issue_details

    Retrieve details of a specific issue by issue ID.

    create_issue

    Create a new issue within a specific project and team.

    update_issue

    Update the title or state of a specific issue by issue ID.

    get_user_assigned_issues

    Retrieve issues assigned to a specific user by user ID.

    get_workflow_issues

    Retrieve issues within a specific workflow state by workflow ID.

    ​
    ​

    Enable create_issue tool.

    read_article

    bool

    True

    Enables the functionality to read the full content of an article.

    include_summary

    bool

    False

    Specifies whether to include a summary of the article along with the full content.

    article_length

    int

    -

    get_article_data

    This function reads the full content and data of an article.

    read_article

    This function reads the full content of an article.

    ​
    https://www.rockymountaineer.com/blog/experience-icefields-parkway-scenic-drive-lifetime
    ​
    ​

    The maximum length of the article or its summary to be processed or returned.

    api_key

    str

    None

    If you want to manually supply the Replicate API key.

    model

    str

    minimax/video-01

    The replicate model to use. Find out more on the Replicate platform.

    generate_media

    Generate either an image or a video from a prompt. The output depends on the model.

    ​
    ​
    ​

    max_results

    int

    -

    The maximum number of search results to return

    url

    str

    -

    The url to be scraped or crawled

    search

    Searches the web for the given query.

    scrape

    Scrapes the given url.

    crawl

    Crawls the given url.

    ​
    ​
    ​

    knowledge_base

    WebsiteKnowledgeBase

    -

    The knowledge base associated with the website, containing various data and resources linked to the website’s content.

    add_website_to_knowledge_base

    This function adds a website’s content to the knowledge base. NOTE: The website must start with https:// and should be a valid website. Use this function to get information about products from the internet.

    read_url

    This function reads a URL and returns the contents.

    ​
    ​
    ​
    import os
    from typing import Iterator
    
    from bitca.agent import Agent, RunResponse
    from bitca.model.azure import AzureOpenAIChat
    
    azure_model = AzureOpenAIChat(
        id=os.getenv("AZURE_OPENAI_MODEL_NAME"),
        api_key=os.getenv("AZURE_OPENAI_API_KEY"),
        azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
        azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT"),
    )
    
    agent = Agent(
        model=azure_model,
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response on the terminal
    agent.print_response("Share a 2 sentence horror story.")
    import typer
    from typing import Optional, List
    from bitca.agent import Agent
    from bitca.storage.agent.postgres import PgAgentStorage
    from bitca.knowledge.pdf import PDFUrlKnowledgeBase
    from bitca.vectordb.pgvector import PgVector, SearchType
    
    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    knowledge_base = PDFUrlKnowledgeBase(
        urls=["https://bitca-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
        vector_db=PgVector(table_name="recipes", db_url=db_url, search_type=SearchType.hybrid),
    )
    # Load the knowledge base: Comment after first run
    knowledge_base.load(upsert=True)
    storage = PgAgentStorage(table_name="pdf_agent", db_url=db_url)
    
    def pdf_agent(new: bool = False, user: str = "user"):
        session_id: Optional[str] = None
    
        if not new:
            existing_sessions: List[str] = storage.get_all_session_ids(user)
            if len(existing_sessions) > 0:
                session_id = existing_sessions[0]
    
        agent = Agent(
            session_id=session_id,
            user_id=user,
            knowledge=knowledge_base,
            storage=storage,
            # Show tool calls in the response
            show_tool_calls=True,
            # Enable the agent to read the chat history
            read_chat_history=True,
            # We can also automatically add the chat history to the messages sent to the model
            # But giving the model the chat history is not always useful, so we give it a tool instead
            # to only use when needed.
            # add_history_to_messages=True,
            # Number of historical responses to add to the messages.
            # num_history_responses=3,
        )
        if session_id is None:
            session_id = agent.session_id
            print(f"Started Session: {session_id}\n")
        else:
            print(f"Continuing Session: {session_id}\n")
    
        # Runs the agent as a cli app
        agent.cli_app(markdown=True)
    
    
    if __name__ == "__main__":
        typer.run(pdf_agent)
    pip install -U bitca openai pgvector pypdf "psycopg[binary]" sqlalchemy
    python agent_with_storage.py
    How do I make pad thai?
    What was my last message?
    python agent_with_storage.py --new
    from bitca.agent import Agent, RunResponse
    from bitca.model.anthropic import Claude
    
    agent = Agent(
        model=Claude(id="claude-3-5-sonnet-20240620"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response on the terminal
    agent.print_response("Share a 2 sentence horror story.")
    from bitca.agent import Agent, RunResponse
    from bitca.model.vertexai import Gemini
    
    agent = Agent(
        model=Gemini(id="gemini-1.5-flash"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response on the terminal
    agent.print_response("Share a 2 sentence horror story.")
    from bitca.agent import Agent, RunResponse
    from bitca.model.aws.claude import Claude
    
    agent = Agent(
        model=Claude(id="anthropic.claude-3-5-sonnet-20240620-v1:0"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response on the terminal
    agent.print_response("Share a 2 sentence horror story.")
    from bitca.agent import Agent, RunResponse
    from bitca.model.together import Together
    
    agent = Agent(
        model=Together(id="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    from bitca.agent import Agent
    from bitca.tools.github import GithubTools
    
    agent = Agent(
        instructions=[
            "Use your tools to answer questions about the repo: bitca/bitca",
            "Do not create any issues or pull requests unless explicitly asked to do so",
        ],
        tools=[GithubTools()],
        show_tool_calls=True,
    )
    agent.print_response("List open pull requests", markdown=True)
    from bitca.agent import Agent
    from bitca.tools.linear_tools import LinearTool
    
    agent = Agent(
        name="Linear Tool Agent",
        tools=[LinearTool()],
        show_tool_calls=True,
        markdown=True,
    )
    agent.print_response("Show all the issues assigned to user id: 12021")
    
    from bitca.agent import Agent
    from bitca.tools.newspaper4k import Newspaper4k
    
    agent = Agent(tools=[Newspaper4k()], debug_mode=True, show_tool_calls=True)
    agent.print_response("Please summarize https://www.rockymountaineer.com/blog/experience-icefields-parkway-scenic-drive-lifetime")
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.replicate import ReplicateTools
    
    """Create an agent specialized for Replicate AI content generation"""
    
    image_agent = Agent(
        name="Image Generator Agent",
        model=OpenAIChat(id="gpt-4o"),
        tools=[ReplicateTools(model="luma/photon-flash")],
        description="You are an AI agent that can generate images using the Replicate API.",
        instructions=[
            "When the user asks you to create an image, use the `generate_media` tool to create the image.",
            "Return the URL as raw to the user.",
            "Don't convert image URL to markdown or anything else.",
        ],
        markdown=True,
        debug_mode=True,
        show_tool_calls=True,
    )
    
    image_agent.print_response("Generate an image of a horse in the dessert.")
    
    from bitca.agent import Agent
    from bitca.tools.spider import SpiderTools
    
    agent = Agent(tools=[SpiderTools()])
    agent.print_response('Can you scrape the first search result from a search on "news in USA"?', markdown=True)
    from bitca.agent import Agent
    from bitca.tools.website import WebsiteTools
    
    agent = Agent(tools=[WebsiteTools()], show_tool_calls=True)
    agent.print_response("Search web page: 'https://docs.projectbit.ca.com/introduction'", markdown=True)

    Create Web Search Agent

    Create a file web_search.py

    web_search.py

    2

    Run the agent

    Install libraries

    Run the agent

    Writing your own Tools

    For more control, write your own python functions and add them as tools to an Agent. For example, here’s how to add a get_top_hackernews_stories tool to an Agent.

    hn_agent.py

    Read more about:

    Attributes

    The following attributes allow an Agent to use tools

    Parameter
    Type
    Default
    Description

    tools

    List[Union[Tool, Toolkit, Callable, Dict, Function]]

    -

    A list of tools provided to the Model. Tools are functions the model may generate JSON inputs for.

    show_tool_calls

    bool

    False

    Print the signature of the tool calls in the Model response.

    tool_call_limit

    int

    -

    ​Example

    Use CohereChat with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "command-r-08-2024"

    The specific model ID used for generating responses.

    name

    str

    "CohereChat"

    The name identifier for the agent.

    provider

    str

    "Cohere"

    ​
    here
    ​Toolkit Params
    Parameter
    Type
    Default
    Description

    csvs

    List[Union[str, Path]]

    -

    A list of CSV files or paths to be processed or read.

    row_limit

    int

    -

    The maximum number of rows to process from each CSV file.

    read_csvs

    bool

    True

    ​Toolkit Functions

    Function
    Description

    list_csv_files

    Lists all available CSV files.

    read_csv_file

    This function reads the contents of a csv file

    get_columns

    This function returns the columns of a csv file

    query_csv_file

    This function queries the contents of a csv file

    ​
    ​Example

    The following agent will analyze the movies file using SQL and return the result.

    cookbook/tools/duckdb_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    db_path

    str

    -

    Specifies the path to the database file.

    connection

    DuckDBPyConnection

    -

    Provides an existing DuckDB connection object.

    init_commands

    List

    -

    ​Toolkit Functions

    Function
    Description

    show_tables

    Function to show tables in the database

    describe_table

    Function to describe a table

    inspect_query

    Function to inspect a query and return the query plan. Always inspect your query before running them.

    run_query

    Function that runs a query and returns the result.

    summarize_table

    Function to compute a number of aggregates over a table. The function launches a query that computes a number of aggregates over all columns, including min, max, avg, std and approx_unique.

    get_table_name_from_path

    Get the table name from a path

    ​
    DuckDB documentation
    ​Example

    The following agent will provide a summary of a YouTube video.

    cookbook/tools/youtube_tools.py

    ​Toolkit Params

    Param
    Type
    Default
    Description

    get_video_captions

    bool

    True

    Enables the functionality to retrieve video captions.

    get_video_data

    bool

    True

    Enables the functionality to retrieve video metadata and other related data.

    languages

    List[str]

    -

    ​Toolkit Functions

    Function
    Description

    get_youtube_video_captions

    This function retrieves the captions of a YouTube video.

    get_youtube_video_data

    This function retrieves the metadata of a YouTube video.

    ​
    are supported natively

    Workflows

    Workflows are deterministic, stateful, multi-agent programs that are built for production applications. They’re incredibly powerful and offer the following benefits:

    • Full control and flexibility: You have full control over the multi-agent process, how the input is processed, which agents are used and in what order. This is critical for reliability.

    • Pure python: Control the agent process using standard python. Having built 100s of AI products, no framework will give you the flexibility of pure-python.

    • Built-in state management and caching: Store state and cache intermediate results in a database, enabling your agents to re-use results from previous executions.

    How to build a workflow:

    1. Define your workflow as a class by inheriting from the Workflow class.

    2. Add one or more agents to the workflow.

    3. Implement your logic in the run() method.

    4. Cache results in the session_state

    Example: Blog Post Generator

    Let’s create a blog post generator that can search the web, read the top links and write a blog post for us. We’ll cache intermediate results in the database to improve performance.

    Create the Workflow

    Create a file blog_post_generator.py

    blog_post_generator.py

    Run the workflow

    Install libraries

    Run the workflow

    Examples

    Research Agent

    Let’s build a research agent to generate a report using Exa.

    1

    Create a research agent

    research_agent.py

    2

    Run the agent

    Install libraries

    Run the agent

    View the report

    Agentic RAG

    We were the first to pioneer Agentic RAG using our Auto-RAG paradigm. With Agentic RAG (or auto-rag), the Agent can search its knowledge base (vector db) for the specific information it needs to achieve its task, instead of always inserting the “context” into the prompt.

    1

    Create a RAG agent

    rag_agent.py

    2

    Run the agent

    Install libraries

    Run the agent

    Structured Outputs

    Agents can return their output in a structured format as a Pydantic model.

    Create a file structured_output.py

    1

    Create a structured output agent

    structured_output.py

    2

    Run the agent

    Reasoning Agent

    Reasoning is an experimental feature that helps agents work through a problem step-by-step, backtracking and correcting as needed.

    1

    Create a reasoning agent

    reasoning_agent.py

    2

    Run the reasoning agent

    Reasoning

    Reasoning Reasoning is an experimental feature that enables an Agent to think through a problem step-by-step before jumping into a response. The Agent works through different ideas, validating and cor

    reasoning_agent.py

    Run the Reasoning Agent:

    How to use reasoning

    To add reasoning, set reasoning=True. When using reasoning with tools, do not use structured_outputs=True as gpt-4o cannot use tools with structured outputs.

    Reasoning with tools

    You can also use tools with a reasoning agent, but do not use structured_outputs=True as gpt-4o cannot use tools with structured outputs. Lets create a finance agent that can reason.

    finance_reasoning.py

    Run the script to see the output.

    More reasoning examples

    Logical puzzles

    logical_puzzle.py

    Run the script to see the output.

    Mathematical proofs

    mathematical_proof.py

    Run the script to see the output.

    Scientific research

    scientific_research.py

    Run the script to see the output.

    Ethical dilemma

    ethical_dilemma.py

    Run the script to see the output.

    Planning an itinerary

    planning_itinerary.py

    Run the script to see the output.

    Creative writing

    creative_writing.py

    Run the script to see the output.

    Google Calendar

    Enable an Agent to work with Google Calendar to view and schedule meetings.

    ​Prerequisites

    ​Install dependencies

    Setup Google Project and OAuth

    Reference:

    1. Enable Google Calender API

      • Go to .

      • Select Project and Enable.

    2. Go To API & Service -> OAuth Consent Screen

    Example

    The following agent will use GoogleCalendarTools to find today’s events.

    cookbook/tools/googlecalendar_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Pyton

    PythonTools enable an Agent to write and run python code.

    ​Example

    The following agent will write a python script that creates the fibonacci series, save it to a file, run it and return the result.

    cookbook/tools/python_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Tavily

    TavilyTools enable an Agent to search the web using the Tavily API.

    ​Prerequisites

    The following examples requires the tavily-python library and an API key from Tavily.

    Example

    The following agent will run a search on Tavily for “language models” and print the response.

    cookbook/tools/tavily_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Docx Knowledge Base

    The DocxKnowledgeBase reads local docx files, converts them into vector embeddings and loads them to a vector databse.

    ​Usage

    We are using a local PgVector database for this example. Make sure it’s running

    pip install textract

    Then use the knowledge_base with an Agent:

    Params

    Parameter
    Type
    Default
    Description

    Introduction

    A knowledge base is a database of information that an agent can search to improve its responses. This information is stored in a vector database and provides agents with business context, helping them respond in a context-aware manner. The general syntax is:

    from bitca.agent import Agent, AgentKnowledge
    
    # Create a knowledge base for the Agent
    knowledge_base = AgentKnowledge(vector_db=...)
    
    # Add information to the knowledge base
    knowledge_base.load_text("The sky is blue")
    
    # Add the knowledge base to the Agent and
    # give it a tool to search the knowledge base as needed
    agent = Agent(knowledge=knowledge_base, search_knowledge=True)

    Vector Databases

    While any type of storage can act as a knowledge base, vector databases offer the best solution for retrieving relevant results from dense information quickly. Here’s how vector databases are used with Agents:

    1

    Chunk the information

    Break down the knowledge into smaller chunks to ensure our search query returns only relevant results.

    2

    Load the knowledge base

    Convert the chunks into embedding vectors and store them in a vector database.

    3

    Search the knowledge base

    When the user sends a message, we convert the input message into an embedding and “search” for nearest neighbors in the vector database.

    Loading the Knowledge Base

    Before you can use a knowledge base, it needs to be loaded with embeddings that will be used for retrieval. Use one of the following knowledge bases to simplify the chunking, loading, searching and optimization process:

    • : Load ArXiv papers to a knowledge base

    • : Combine multiple knowledge bases into 1

    • : Load CSV files to a knowledge base

    • : Load local docx files to a knowledge base

    Slack

    Prerequisites

    The following example requires the slack-sdk library.

    Get a Slack token from here.

    Example

    The following agent will use Slack to send a message to a channel, list all channels, and get the message history of a specific channel.

    cookbook/tools/slack_tools.py

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Information

    • View on

    Bitca

    Example

    The following agent will use the Bitca toolkit to create and manage bitca workspaces. It can create new applications from templates like llm-app, api-app, django-app, and streamlit-app. It can also start existing workspaces and validate that Bitca is ready to run commands.

    cookbook/tools/bitca_tools.py

    from bitca.agent import Agent
    from bitca.tools.bitca import BitcaTools
    
    # Create an Agent with the bitca tool
    agent = Agent(tools=[bitcaTools()], name="bitca Workspace Manager")
    
    # Example 1: Create a new agent app
    agent.print_response("Create a new agent-app called agent-app-turing", markdown=True)
    
    # Example 3: Start a workspace
    agent.print_response("Start the workspace agent-app-turing", markdown=True)

    Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Knowledge

    Agents use knowledge to supplement their training data with domain expertise.

    Knowledge is stored in a vector database and provides agents with business context at query time, helping them respond in a context-aware manner. The general syntax is:

    Vector Databases

    While any type of storage can act as a knowledge base, vector databases offer the best solution for retrieving relevant results from dense information quickly. Here’s how vector databases are used with Agents:

    1

    HuggingFace

    Authentication

    Set your HF_TOKEN environment. You can get one .

    MacWindows

    Mistral

    Mistral is a platform for providing endpoints for Large Language models.

    Authentication

    Set your MISTRAL_API_KEY environment variable. Get your key from .

    MacWindows

    Groq

    Groq offers blazing-fast API endpoints for large language models

    Authentication

    Set your GROQ_API_KEY environment variable. Get your key from .

    MacWindows

    MLX Transcribe

    MLX Transcribe is a tool for transcribing audio files using MLX Whisper.

    Prerequisites

    1. Install ffmpeg

    Postgres

    PostgresTools enable an Agent to interact with a PostgreSQL database.

    Prerequisites

    The following example requires the psycopg2 library.

    You will also need a database. The following example uses a Postgres database running in a Docker container.

    CSV URL Knowledge Base

    The CSVUrlKnowledgeBase reads CSVs from urls, converts them into vector embeddings and loads them to a vector database.

    Usage

    We are using a local PgVector database for this example.

    knowledge_base.py

    Then use the knowledge_base with an Agent:

    agent.py

    Zendesk

    ZendeskTools enable an Agent to access Zendesk API to search for articles.

    Prerequisites

    The following example requires the requests library and auth credentials.

    from bitca.agent import Agent
    from bitca.tools.duckduckgo import DuckDuckGo
    
    agent = Agent(tools=[DuckDuckGo()], show_tool_calls=True, markdown=True)
    agent.print_response("Whats happening in France?", stream=True)
    pip install openai duckduckgo-search bitca
    python web_search.py
    from bitca.agent import Agent
    
    agent = Agent(
        # Add functions or Toolkits
        tools=[...],
        # Show tool calls in the Agent response
        show_tool_calls=True
    )
    export CO_API_KEY=***
    from bitca.agent import Agent, RunResponse
    from bitca.model.cohere import CohereChat
    
    agent = Agent(
        model=CohereChat(id="command-r-08-2024"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    import httpx
    from pathlib import Path
    from bitca.agent import Agent
    from bitca.tools.csv_tools import CsvTools
    
    url = "https://bitca-public.s3.amazonaws.com/demo_data/IMDB-Movie-Data.csv"
    response = httpx.get(url)
    
    imdb_csv = Path(__file__).parent.joinpath("wip").joinpath("imdb.csv")
    imdb_csv.parent.mkdir(parents=True, exist_ok=True)
    imdb_csv.write_bytes(response.content)
    
    agent = Agent(
        tools=[CsvTools(csvs=[imdb_csv])],
        markdown=True,
        show_tool_calls=True,
        instructions=[
            "First always get the list of files",
            "Then check the columns in the file",
            "Then run the query to answer the question",
        ],
    )
    agent.cli_app(stream=False)
    pip install duckdb
    from bitca.agent import Agent
    from bitca.tools.duckdb import DuckDbTools
    
    agent = Agent(
        tools=[DuckDbTools()],
        show_tool_calls=True,
        system_prompt="Use this file for Movies data: https://bitca-public.s3.amazonaws.com/demo_data/IMDB-Movie-Data.csv",
    )
    agent.print_response("What is the average rating of movies?", markdown=True, stream=False)
    pip install -U youtube_transcript_api
    from bitca.agent import Agent
    from bitca.tools.youtube_tools import YouTubeTools
    
    agent = Agent(
        tools=[YouTubeTools()],
        show_tool_calls=True,
        description="You are a YouTube agent. Obtain the captions of a YouTube video and answer questions.",
    )
    
    agent.print_response("Summarize this video https://www.youtube.com/watch?v=Iv9dewmcFbs&t", markdown=True)
    const handleFetchEvent = async (request, context) => {
        return new Response({message: "Hello World"});
    };
    from textwrap import dedent
    from datetime import datetime
    
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.exa import ExaTools
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        tools=[ExaTools(start_published_date=datetime.now().strftime("%Y-%m-%d"), type="keyword")],
        description="You are an advanced AI researcher writing a report on a topic.",
        instructions=[
            "For the provided topic, run 3 different searches.",
            "Read the results carefully and prepare a NYT worthy report.",
            "Focus on facts and make sure to provide references.",
        ],
        expected_output=dedent("""\
        An engaging, informative, and well-structured report in markdown format:
    
        ## Engaging Report Title
    
        ### Overview
        {give a brief introduction of the report and why the user should read this report}
        {make this section engaging and create a hook for the reader}
    
        ### Section 1
        {break the report into sections}
        {provide details/facts/processes in this section}
    
        ... more sections as necessary...
    
        ### Takeaways
        {provide key takeaways from the article}
    
        ### References
        - [Reference 1](link)
        - [Reference 2](link)
        - [Reference 3](link)
    
        - published on {date} in dd/mm/yyyy
        """),
        markdown=True,
        show_tool_calls=True,
        add_datetime_to_instructions=True,
        save_response_to_file="tmp/{message}.md",
    )
    agent.print_response("Simulation theory", stream=True)
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = (
        "Three missionaries and three cannibals need to cross a river. "
        "They have a boat that can carry up to two people at a time. "
        "If, at any time, the cannibals outnumber the missionaries on either side of the river, the cannibals will eat the missionaries. "
        "How can all six people get across the river safely? Provide a step-by-step solution and show the solutions as an ascii diagram"
    )
    
    reasoning_agent = Agent(model=OpenAIChat(id="gpt-4o"), reasoning=True, markdown=True, structured_outputs=True)
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python reasoning_agent.py
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"),
        reasoning=True,
        markdown=True,
        structured_outputs=True,
    )
    reasoning_agent.print_response("How many 'r' are in the word 'supercalifragilisticex
    pip install tzlocal
    from bitca.agent import Agent
    from bitca.tools.python import PythonTools
    
    agent = Agent(tools=[PythonTools()], show_tool_calls=True)
    agent.print_response("Write a python script for fibonacci series and display the result till the 10th number")
    pip install -U tavily-python
    export TAVILY_API_KEY=***
    from bitca.knowledge.docx import DocxKnowledgeBase
    from bitca.vectordb.pgvector import PgVector
    
    knowledge_base = DocxKnowledgeBase(
        path="data/docs",
        # Table name: ai.docx_documents
        vector_db=PgVector(
            table_name="docx_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )
    from bitca.agent import Agent
    from knowledge_base import knowledge_base
    
    agent = Agent(
        knowledge=knowledge_base,
        search_knowledge=True,
    )
    agent.knowledge.load(recreate=False)
    
    agent.print_response("Ask me about something from the knowledge base")
    pip install openai slack-sdk
    export SLACK_TOKEN=***

    The provider of the model.

    temperature

    Optional[float]

    -

    The sampling temperature to use, between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic.

    max_tokens

    Optional[int]

    -

    The maximum number of tokens to generate in the response.

    top_k

    Optional[int]

    -

    The number of highest probability vocabulary tokens to keep for top-k-filtering.

    top_p

    Optional[float]

    -

    Nucleus sampling parameter. The model considers the results of the tokens with top_p probability mass.

    frequency_penalty

    Optional[float]

    -

    Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.

    presence_penalty

    Optional[float]

    -

    Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

    request_params

    Optional[Dict[str, Any]]

    -

    Additional parameters to include in the request.

    add_chat_history

    bool

    False

    Whether to add chat history to the Cohere messages instead of using the conversation_id.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the Cohere service.

    client_params

    Optional[Dict[str, Any]]

    -

    Additional parameters for client configuration.

    cohere_client

    Optional[CohereClient]

    -

    A pre-configured instance of the Cohere client.

    Enables the functionality to read data from specified CSV files.

    list_csvs

    bool

    True

    Enables the functionality to list all available CSV files.

    query_csvs

    bool

    True

    Enables the functionality to execute queries on data within CSV files.

    read_column_names

    bool

    True

    Enables the functionality to read the column names from the CSV files.

    duckdb_connection

    Any

    -

    Specifies a connection instance for DuckDB database operations.

    duckdb_kwargs

    Dict[str, Any]

    -

    A dictionary of keyword arguments for configuring DuckDB operations.

    A list of initial SQL commands to run on database connection.

    read_only

    bool

    False

    Configures the database connection to be read-only.

    config

    dict

    -

    Configuration options for the database connection.

    run_queries

    bool

    True

    Determines whether to run SQL queries during the operation.

    inspect_queries

    bool

    False

    Enables inspection of SQL queries without executing them.

    create_tables

    bool

    True

    Allows creation of tables in the database during the operation.

    summarize_tables

    bool

    True

    Enables summarization of table data during the operation.

    export_tables

    bool

    False

    Allows exporting tables to external formats during the operation.

    create_table_from_path

    Creates a table from a path

    export_table_to_path

    Save a table in a desired format (default: parquet). If the path is provided, the table will be saved under that path. Eg: If path is /tmp, the table will be saved as /tmp/table.parquet. Otherwise it will be saved in the current directory

    load_local_path_to_table

    Load a local file into duckdb

    load_local_csv_to_table

    Load a local CSV file into duckdb

    load_s3_path_to_table

    Load a file from S3 into duckdb

    load_s3_csv_to_table

    Load a CSV file from S3 into duckdb

    create_fts_index

    Create a full text search index on a table

    full_text_search

    Full text Search in a table column for a specific text/keyword

    Specifies the list of languages for which data should be retrieved, if applicable.

    JSON knowledge base: Load JSON files to a knowledge base

  • LangChain knowledge base: Use a Langchain retriever as a knowledge base

  • PDF knowledge base: Load local PDF files to a knowledge base

  • PDF URL knowledge base: Load PDF files from a URL to a knowledge base

  • S3 PDF knowledge base: Load PDF files from S3 to a knowledge base

  • S3 Text knowledge base: Load text files from S3 to a knowledge base

  • Text knowledge base: Load text/docx files to a knowledge base

  • Website knowledge base: Load website data to a knowledge base

  • Wikipedia knowledge base: Load wikipedia articles to a knowledge base

  • ​
    ArXiv knowledge base
    Combined knowledge base
    CSV knowledge base
    Document knowledge base

    name

    str

    "bitca_tools"

    The name of the tool

    validate_bitca_is_ready

    Validates that bitca is ready to run commands

    create_new_app

    Creates a new bitca workspace for a given application template

    start_user_workspace

    Starts the workspace for a user

    ​
    ​

    run_code

    bool

    False

    Determines whether the code should be executed.

    list_files

    bool

    False

    If True, lists all files in the specified base directory.

    run_files

    bool

    False

    If True, runs the Python files found in the specified directory.

    read_files

    bool

    False

    If True, reads the contents of the files in the specified directory.

    safe_globals

    dict

    -

    Specifies a dictionary of global variables that are considered safe to use during the execution.

    safe_locals

    dict

    -

    Specifies a dictionary of local variables that are considered safe to use during the execution.

    base_dir

    Path

    None

    Specifies the base directory for operations. Default is None, indicating the current working directory.

    save_and_run

    bool

    True

    If True, saves and runs the code. Useful for execution of scripts after saving.

    pip_install

    bool

    False

    save_to_file_and_run

    This function saves Python code to a file called file_name and then runs it. If successful, returns the value of variable_to_return if provided otherwise returns a success message. If failed, returns an error message. Make sure the file_name ends with .py

    run_python_file_return_variable

    This function runs code in a Python file. If successful, returns the value of variable_to_return if provided otherwise returns a success message. If failed, returns an error message.

    read_file

    Reads the contents of the file file_name and returns the contents if successful.

    list_files

    Returns a list of files in the base directory

    run_python_code

    This function runs Python code in the current environment. If successful, returns the value of variable_to_return if provided otherwise returns a success message. If failed, returns an error message.

    pip_install_package

    This function installs a package using pip in the current environment. If successful, returns a success message. If failed, returns an error message.

    ​
    ​

    Enables pip installation of required packages before running the code.

    vector_db

    VectorDb

    -

    Vector Database for the Knowledge Base.

    num_documents

    int

    5

    Number of documents to return on search.

    optimize_on

    int

    -

    Number of documents to optimize the vector db on.

    chunking_strategy

    ChunkingStrategy

    FixedSizeChunking

    The chunking strategy to use.

    path

    Union[str, Path]

    -

    Path to docx files. Can point to a single docx file or a directory of docx files.

    formats

    List[str]

    [".doc", ".docx"]

    Formats accepted by this knowledge base.

    reader

    DocxReader

    DocxReader()

    ​

    A DocxReader that converts the docx files into Documents for the vector database.

    Maximum number of tool calls allowed.

    tool_choice

    Union[str, Dict[str, Any]]

    -

    Controls which (if any) tool is called by the model. “none” means the model will not call a tool and instead generates a message. “auto” means the model can pick between generating a message or calling a tool. Specifying a particular function via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool. “none” is the default when no tools are present. “auto” is the default if tools are present.

    read_chat_history

    bool

    False

    Add a tool that allows the Model to read the chat history.

    search_knowledge

    bool

    False

    Add a tool that allows the Model to search the knowledge base (aka Agentic RAG).

    update_knowledge

    bool

    False

    Add a tool that allows the Model to update the knowledge base.

    read_tool_call_history

    bool

    False

    Add a tool that allows the Model to get the tool call history.

    Available toolkits
    Using functions as tools
    as needed.
  • Run the workflow using the .run() method.

  • This saves tokens and improves response quality.
    ​
    ​
    ​
    ​
    ​
    ​

    Select User Type

    • If you are a Google Workspace user, select Internal.

    • Otherwise, select External.

  • Fill in the app details (App name, logo, support email, etc).

  • Select Scope

    • Click on Add or Remove Scope.

    • Search for Google Calender API (Make sure you’ve enabled Google calender API otherwise scopes wont be visible).

    • Select scopes accordingly

      • From the dropdown check on /auth/calendar scope

    • Save and continue.

  • Adding Test User

    • Click Add Users and enter the email addresses of the users you want to allow during testing.

    • NOTE : Only these users can access the app’s OAuth functionality when the app is in “Testing” mode. Any other users will receive access denied errors.

    • To make the app available to all users, you’ll need to move the app’s status to “In Production”. Before doing so, ensure the app is fully verified by Google if it uses sensitive or restricted scopes.

    • Click on Go back to Dashboard.

  • Generate OAuth 2.0 Client ID

    • Go to Credentials.

    • Click on Create Credentials -> OAuth Client ID

    • Select Application Type as Desktop app.

    • Download JSON.

  • Using Google Calender Tool

    • Pass the path of downloaded credentials as credentials_path to Google Calender tool.

    • Optional: Set the token_path parameter to specify where the tool should create the token.json file.

    • The token.json file is used to store the user’s access and refresh tokens and is automatically created during the authorization flow if it doesn’t already exist.

    • If token_path is not explicitly provided, the file will be created in the default location which is your current working directory.

    • If you choose to specify token_path, please ensure that the directory you provide has write access, as the application needs to create or update this file during the authentication process.

  • credentials_path

    str

    None

    Path of the file credentials.json file which contains OAuth 2.0 Client ID.

    token_path

    str

    None

    Path of the file token.json which stores the user’s access and refresh tokens.

    list_events

    List events from the user’s primary calendar.

    create_event

    Create a new event in the user’s primary calendar.

    ​
    https://developers.google.com/calendar/api/quickstart/python
    Google Cloud Console
    ​
    ​
    ​

    include_answer

    bool

    True

    Whether to include an AI-generated answer summary in the response.

    search_depth

    Literal['basic', 'advanced']

    'advanced'

    Depth of search - ‘basic’ for faster results or ‘advanced’ for more comprehensive search.

    format

    Literal['json', 'markdown']

    'markdown'

    Output format - ‘json’ for raw data or ‘markdown’ for formatted text.

    use_search_context

    bool

    False

    Whether to use Tavily’s search context API instead of regular search.

    api_key

    str

    -

    API key for authentication. If not provided, will check TAVILY_API_KEY environment variable.

    search

    bool

    True

    Enables search functionality.

    max_tokens

    int

    6000

    web_search_using_tavily

    Searches the web for a query using Tavily API. Takes a query string and optional max_results parameter (default 5). Returns results in specified format with titles, URLs, content and relevance scores.

    web_search_with_tavily

    Alternative search function that uses Tavily’s search context API. Takes a query string and returns contextualized search results. Only available if use_search_context is True.

    ​
    ​
    ​

    Maximum number of tokens to use in search results.

    get_channel_history

    bool

    True

    Enables the functionality to retrieve message history from channels

    token

    str

    -

    Slack API token for authentication

    send_message

    bool

    True

    Enables the functionality to send messages to Slack channels

    list_channels

    bool

    True

    send_message

    Sends a message to a specified Slack channel

    list_channels

    Lists all available channels in the Slack workspace

    get_channel_history

    Retrieves message history from a specified channel

    ​
    ​
    ​
    ​
    Github

    Enables the functionality to list available Slack channels

    import json
    import httpx
    
    from bitca.agent import Agent
    
    
    def get_top_hackernews_stories(num_stories: int = 10) -> str:
        """Use this function to get top stories from Hacker News.
    
        Args:
            num_stories (int): Number of stories to return. Defaults to 10.
    
        Returns:
            str: JSON string of top stories.
        """
    
        # Fetch top story IDs
        response = httpx.get('https://hacker-news.firebaseio.com/v0/topstories.json')
        story_ids = response.json()
    
        # Fetch story details
        stories = []
        for story_id in story_ids[:num_stories]:
            story_response = httpx.get(f'https://hacker-news.firebaseio.com/v0/item/{story_id}.json')
            story = story_response.json()
            if "text" in story:
                story.pop("text", None)
            stories.append(story)
        return json.dumps(stories)
    
    agent = Agent(tools=[get_top_hackernews_stories], show_tool_calls=True, markdown=True)
    agent.print_response("Summarize the top 5 stories on hackernews?", stream=True)
    import json
    from typing import Optional, Iterator
    
    from pydantic import BaseModel, Field
    
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.workflow import Workflow, RunResponse, RunEvent
    from bitca.storage.workflow.sqlite import SqlWorkflowStorage
    from bitca.tools.duckduckgo import DuckDuckGo
    from bitca.utils.pprint import pprint_run_response
    from bitca.utils.log import logger
    
    
    class NewsArticle(BaseModel):
        title: str = Field(..., description="Title of the article.")
        url: str = Field(..., description="Link to the article.")
        summary: Optional[str] = Field(..., description="Summary of the article if available.")
    
    
    class SearchResults(BaseModel):
        articles: list[NewsArticle]
    
    
    class BlogPostGenerator(Workflow):
        # Define an Agent that will search the web for a topic
        searcher: Agent = Agent(
            model=OpenAIChat(id="gpt-4o-mini"),
            tools=[DuckDuckGo()],
            instructions=["Given a topic, search for the top 5 articles."],
            response_model=SearchResults,
            structured_outputs=True,
        )
    
        # Define an Agent that will write the blog post
        writer: Agent = Agent(
            model=OpenAIChat(id="gpt-4o"),
            instructions=[
                "You will be provided with a topic and a list of top articles on that topic.",
                "Carefully read each article and generate a New York Times worthy blog post on that topic.",
                "Break the blog post into sections and provide key takeaways at the end.",
                "Make sure the title is catchy and engaging.",
                "Always provide sources, do not make up information or sources.",
            ],
            markdown=True,
        )
    
        def run(self, topic: str, use_cache: bool = True) -> Iterator[RunResponse]:
            """This is where the main logic of the workflow is implemented."""
    
            logger.info(f"Generating a blog post on: {topic}")
    
            # Step 1: Use the cached blog post if use_cache is True
            if use_cache:
                cached_blog_post = self.get_cached_blog_post(topic)
                if cached_blog_post:
                    yield RunResponse(content=cached_blog_post, event=RunEvent.workflow_completed)
                    return
    
            # Step 2: Search the web for articles on the topic
            search_results: Optional[SearchResults] = self.get_search_results(topic)
            # If no search_results are found for the topic, end the workflow
            if search_results is None or len(search_results.articles) == 0:
                yield RunResponse(
                    event=RunEvent.workflow_completed,
                    content=f"Sorry, could not find any articles on the topic: {topic}",
                )
                return
    
            # Step 3: Write a blog post
            yield from self.write_blog_post(topic, search_results)
    
        def get_cached_blog_post(self, topic: str) -> Optional[str]:
            """Get the cached blog post for a topic."""
    
            logger.info("Checking if cached blog post exists")
            return self.session_state.get("blog_posts", {}).get(topic)
    
        def add_blog_post_to_cache(self, topic: str, blog_post: Optional[str]):
            """Add a blog post to the cache."""
    
            logger.info(f"Saving blog post for topic: {topic}")
            self.session_state.setdefault("blog_posts", {})
            self.session_state["blog_posts"][topic] = blog_post
    
        def get_search_results(self, topic: str) -> Optional[SearchResults]:
            """Get the search results for a topic."""
    
            MAX_ATTEMPTS = 3
    
            for attempt in range(MAX_ATTEMPTS):
                try:
                    searcher_response: RunResponse = self.searcher.run(topic)
    
                    # Check if we got a valid response
                    if not searcher_response or not searcher_response.content:
                        logger.warning(f"Attempt {attempt + 1}/{MAX_ATTEMPTS}: Empty searcher response")
                        continue
                    # Check if the response is of the expected SearchResults type
                    if not isinstance(searcher_response.content, SearchResults):
                        logger.warning(f"Attempt {attempt + 1}/{MAX_ATTEMPTS}: Invalid response type")
                        continue
    
                    article_count = len(searcher_response.content.articles)
                    logger.info(f"Found {article_count} articles on attempt {attempt + 1}")
                    return searcher_response.content
    
                except Exception as e:
                    logger.warning(f"Attempt {attempt + 1}/{MAX_ATTEMPTS} failed: {str(e)}")
    
            logger.error(f"Failed to get search results after {MAX_ATTEMPTS} attempts")
            return None
    
        def write_blog_post(self, topic: str, search_results: SearchResults) -> Iterator[RunResponse]:
            """Write a blog post on a topic."""
    
            logger.info("Writing blog post")
            # Prepare the input for the writer
            writer_input = {"topic": topic, "articles": [v.model_dump() for v in search_results.articles]}
            # Run the writer and yield the response
            yield from self.writer.run(json.dumps(writer_input, indent=4), stream=True)
            # Save the blog post in the cache
            self.add_blog_post_to_cache(topic, self.writer.run_response.content)
    
    
    # Run the workflow if the script is executed directly
    if __name__ == "__main__":
        from rich.prompt import Prompt
    
        # Get topic from user
        topic = Prompt.ask(
            "[bold]Enter a blog post topic[/bold]\n✨",
            default="Why Cats Secretly Run the Internet",
        )
    
        # Convert the topic to a URL-safe string for use in session_id
        url_safe_topic = topic.lower().replace(" ", "-")
    
        # Initialize the blog post generator workflow
        # - Creates a unique session ID based on the topic
        # - Sets up SQLite storage for caching results
        generate_blog_post = BlogPostGenerator(
            session_id=f"generate-blog-post-on-{url_safe_topic}",
            storage=SqlWorkflowStorage(
                table_name="generate_blog_post_workflows",
                db_file="tmp/workflows.db",
            ),
        )
    
        # Execute the workflow with caching enabled
        # Returns an iterator of RunResponse objects containing the generated content
        blog_post: Iterator[RunResponse] = generate_blog_post.run(topic=topic, use_cache=True)
    
        # Print the response
        pprint_run_response(blog_post, markdown=True)
    pip install bitca openai duckduckgo-search sqlalchemy
    python blog_post_generator.py
    pip install openai exa-py bitca
    python research_agent.py
    cat tmp/Simulation theory.md
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.embedder.openai import OpenAIEmbedder
    from bitca.knowledge.pdf import PDFUrlKnowledgeBase
    from bitca.vectordb.lancedb import LanceDb, SearchType
    
    # Create a knowledge base from a PDF
    knowledge_base = PDFUrlKnowledgeBase(
        urls=["https://bitca-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
        # Use LanceDB as the vector database
        vector_db=LanceDb(
            table_name="recipes",
            uri="tmp/lancedb",
            search_type=SearchType.vector,
            embedder=OpenAIEmbedder(model="text-embedding-3-small"),
        ),
    )
    # Comment out after first run as the knowledge base is loaded
    knowledge_base.load()
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        # Add the knowledge base to the agent
        knowledge=knowledge_base,
        show_tool_calls=True,
        markdown=True,
    )
    agent.print_response("How do I make chicken and galangal in coconut milk sou
    pip install lancedb tantivy pypdf sqlalchemy
    python rag_agent.py
    from typing import List
    from pydantic import BaseModel, Field
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    # Define a Pydantic model to enforce the structure of the output
    class MovieScript(BaseModel):
        setting: str = Field(..., description="Provide a nice setting for a blockbuster movie.")
        ending: str = Field(..., description="Ending of the movie. If not available, provide a happy ending.")
        genre: str = Field(..., description="Genre of the movie. If not available, select action, thriller or romantic comedy.")
        name: str = Field(..., description="Give a name to this movie")
        characters: List[str] = Field(..., description="Name of characters for this movie.")
        storyline: str = Field(..., description="3 sentence storyline for the movie. Make it exciting!")
    
    # Agent that uses JSON mode
    json_mode_agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        description="You write movie scripts.",
        response_model=MovieScript,
    )
    # Agent that uses structured outputs
    structured_output_agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        description="You write movie scripts.",
        response_model=MovieScript,
        structured_outputs=True,
    )
    
    json_mode_agent.print_response("New York")
    structured_output_agent.print_response("New York")
    python structured_output.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = (
        "Three missionaries and three cannibals need to cross a river. "
        "They have a boat that can carry up to two people at a time. "
        "If, at any time, the cannibals outnumber the missionaries on either side of the river, the cannibals will eat the missionaries. "
        "How can all six people get across the river safely? Provide a step-by-step solution and show the solutions as an ascii diagram"
    )
    
    reasoning_agent = Agent(model=OpenAIChat(id="gpt-4o"), reasoning=True, markdown=True, structured_outputs=True)
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    python reasoning_agent.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.yfinance import YFinanceTools
    
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        tools=[YFinanceTools(stock_price=True, analyst_recommendations=True, company_info=True, company_news=True)],
        instructions=["Use tables to show data"],
        show_tool_calls=True,
        markdown=True,
        reasoning=True,
    )
    reasoning_agent.print_response("Write a report comparing NVDA to TSLA", stream=True, show_full_reasoning=True)
    pip install -U bitca openai yfinance
    
    export OPENAI_API_KEY=***
    
    python finance_reasoning.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = (
        "Three missionaries and three cannibals need to cross a river. "
        "They have a boat that can carry up to two people at a time. "
        "If, at any time, the cannibals outnumber the missionaries on either side of the river, the cannibals will eat the missionaries. "
        "How can all six people get across the river safely? Provide a step-by-step solution and show the solutions as an ascii diagram"
    )
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"), reasoning=True, markdown=True, structured_outputs=True
    )
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python logical_puzzle.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = "Prove that for any positive integer n, the sum of the first n odd numbers is equal to n squared. Provide a detailed proof."
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"), reasoning=True, markdown=True, structured_outputs=True
    )
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python mathematical_proof.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = (
        "Read the following abstract of a scientific paper and provide a critical evaluation of its methodology,"
        "results, conclusions, and any potential biases or flaws:\n\n"
        "Abstract: This study examines the effect of a new teaching method on student performance in mathematics. "
        "A sample of 30 students was selected from a single school and taught using the new method over one semester. "
        "The results showed a 15% increase in test scores compared to the previous semester. "
        "The study concludes that the new teaching method is effective in improving mathematical performance among high school students."
    )
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"), reasoning=True, markdown=True, structured_outputs=True
    )
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python scientific_research.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = (
        "You are a train conductor faced with an emergency: the brakes have failed, and the train is heading towards "
        "five people tied on the track. You can divert the train onto another track, but there is one person tied there. "
        "Do you divert the train, sacrificing one to save five? Provide a well-reasoned answer considering utilitarian "
        "and deontological ethical frameworks. "
        "Provide your answer also as an ascii art diagram."
    )
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"), reasoning=True, markdown=True, structured_outputs=True
    )
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python ethical_dilemma.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = "Plan an itinerary from Los Angeles to Las Vegas"
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"), reasoning=True, markdown=True, structured_outputs=True
    )
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python planning_itinerary.py
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    
    task = "Write a short story about life in 5000000 years"
    reasoning_agent = Agent(
        model=OpenAIChat(id="gpt-4o-2024-08-06"), reasoning=True, markdown=True, structured_outputs=True
    )
    reasoning_agent.print_response(task, stream=True, show_full_reasoning=True)
    pip install -U bitca openai
    
    export OPENAI_API_KEY=***
    
    python creative_writing.py
    from bitca.agent import Agent
    from bitca.tools.googlecalendar import GoogleCalendarTools
    import datetime
    import os
    from tzlocal import get_localzone_name
    
    agent = Agent(
        tools=[GoogleCalendarTools(credentials_path="<PATH_TO_YOUR_CREDENTIALS_FILE>")],
        show_tool_calls=True,
        instructions=[
            f"""
            You are scheduling assistant . Today is {datetime.datetime.now()} and the users timezone is {get_localzone_name()}.
            You should help users to perform these actions in their Google calendar:
                - get their scheduled events from a certain date and time
                - create events based on provided details
            """
        ],
        add_datetime_to_instructions=True,
    )
    
    agent.print_response("Give me the list of todays events", markdown=True)
    
    
    from bitca.agent import Agent
    from bitca.tools.tavily import TavilyTools
    
    agent = Agent(tools=[TavilyTools()], show_tool_calls=True)
    agent.print_response("Search tavily for 'language models'", markdown=True)
    import os
    
    from bitca.agent import Agent
    from bitca.tools.slack import SlackTools
    
    
    slack_tools = SlackTools()
    
    agent = Agent(tools=[slack_tools], show_tool_calls=True)
    
    # Example 1: Send a message to a Slack channel
    agent.print_response("Send a message 'Hello from bitca !' to the channel #general", markdown=True)
    
    # Example 2: List all channels in the Slack workspace
    agent.print_response("List all channels in our Slack workspace", markdown=True)
    
    # Example 3: Get the message history of a specific channel by channel ID 
    agent.print_response("Get the last 10 messages from the channel 1231241", markdown=True)
    

    Chunk the information

    Break down the knowledge into smaller chunks to ensure our search query returns only relevant results.

    2

    Load the knowledge base

    Convert the chunks into embedding vectors and store them in a vector database.

    3

    Search the knowledge base

    When the user sends a message, we convert the input message into an embedding and “search” for nearest neighbors in the vector database.

    Example: RAG Agent with a PDF Knowledge Base

    Let’s build a RAG Agent that answers questions from a PDF.

    Step 1: Run PgVector

    Let’s use PgVector as our vector db as it can also provide storage for our Agents.

    Install docker desktop and run PgVector on port 5532 using:

    Step 2: Traditional RAG

    Retrieval Augmented Generation (RAG) means “stuffing the prompt with relevant information” to improve the model’s response. This is a 2 step process:

    1. Retrieve relevant information from the knowledge base.

    2. Augment the prompt to provide context to the model.

    Let’s build a traditional RAG Agent that answers questions from a PDF of recipes.

    1
    2

    Create a Traditional RAG Agent

    Create a file traditional_rag.py with the following contents

    traditional_rag.py

    3

    Run the agent

    Run the agent (it takes a few seconds to load the knowledge base).

    Step 3: Agentic RAG

    With traditional RAG above, add_context=True always adds information from the knowledge base to the prompt, regardless of whether it is relevant to the question or helpful.

    With Agentic RAG, we let the Agent decide if it needs to access the knowledge base and what search parameters it needs to query the knowledge base.

    Set search_knowledge=True and read_chat_history=True, giving the Agent tools to search its knowledge and chat history on demand.

    1

    Create an Agentic RAG Agent

    Create a file agentic_rag.py with the following contents

    agentic_rag.py

    2

    Run the agent

    Run the agent

    Attributes

    Parameter
    Type
    Default
    Description

    knowledge

    AgentKnowledge

    None

    Provides the knowledge base used by the agent.

    search_knowledge

    bool

    True

    Adds a tool that allows the Model to search the knowledge base (aka Agentic RAG). Enabled by default when knowledge is provided.

    add_context

    bool

    False

    ​Example

    Use HuggingFace with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "meta-llama/Meta-Llama-3-8B-Instruct"

    The id of the HuggingFace model to use.

    name

    str

    "HuggingFaceChat"

    The name of this chat model instance.

    provider

    str

    "HuggingFace"

    from HuggingFace here
    ​Example

    Use Mistral with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "mistral-large-latest"

    The ID of the model.

    name

    str

    "MistralChat"

    The name of the model.

    provider

    str

    "Mistral"

    ​
    here
    ​Example

    Use Groq with your Agent:

    agent.py

    ​Params

    Parameter
    Type
    Default
    Description

    id

    str

    "llama3-groq-70b-8192-tool-use-preview"

    The specific model ID used for generating responses.

    name

    str

    "Groq"

    The name identifier for the agent.

    provider

    str

    "Groq"

    ​
    here

    macOS: brew install ffmpeg

  • Ubuntu: sudo apt-get install ffmpeg

  • Windows: Download from https://ffmpeg.org/download.html

  • Install mlx-whisper library

  • Prepare audio files

    • Create a ‘storage/audio’ directory

    • Place your audio files in this directory

    • Supported formats: mp3, mp4, wav, etc.

  • Download sample audio (optional)

    • Visit: https://www.ted.com/talks/reid_hoffman_and_kevin_scott_the_evolution_of_ai_and_how_it_will_impact_human_creativity

    • Save the audio file to ‘storage/audio’ directory

  • ​Example

    The following agent will use MLX Transcribe to transcribe audio files.

    cookbook/tools/mlx_transcribe_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    base_dir

    Path

    Path.cwd()

    Base directory for audio files

    read_files_in_base_dir

    bool

    True

    Whether to register the read_files function

    path_or_hf_repo

    str

    "mlx-community/whisper-large-v3-turbo"

    ​Toolkit Functions

    Function
    Description

    transcribe

    Transcribes an audio file using MLX Whisper

    read_files

    Lists all audio files in the base directory

    ​
    ​Example

    The following agent will list all tables in the database.

    cookbook/tools/postgres.py

    ​Toolkit Params

    Name
    Type
    Default
    Description

    connection

    psycopg2.extensions.connection

    None

    Optional database connection object.

    db_name

    str

    None

    Optional name of the database to connect to.

    user

    str

    None

    ​Toolkit Functions

    Function
    Description

    show_tables

    Retrieves and displays a list of tables in the database. Returns the list of tables.

    describe_table

    Describes the structure of a specified table by returning its columns, data types, and maximum character length. Parameters include ‘table’ to specify the table name. Returns the table description.

    summarize_table

    Summarizes a table by computing aggregates such as min, max, average, standard deviation, and non-null counts for numeric columns. Parameters include ‘table’ to specify the table name, and an optional ‘table_schema’ to specify the schema (default is “public”). Returns the summary of the table.

    inspect_query

    Inspects an SQL query by returning the query plan. Parameters include ‘query’ to specify the SQL query. Returns the query plan.

    export_table_to_path

    Exports a specified table in CSV format to a given path. Parameters include ‘table’ to specify the table name and an optional ‘path’ to specify where to save the file (default is the current directory). Returns the result of the export operation.

    run_query

    Executes an SQL query and returns the result. Parameters include ‘query’ to specify the SQL query. Returns the result of the query execution.

    ​
    ​Params
    Parameter
    Type
    Default
    Description

    urls

    List[str]

    -

    URLs for PDF files.

    reader

    CSVUrlReader

    CSVUrlReader()

    A CSVUrlReader that converts the CSVs into Documents for the vector database.

    vector_db

    VectorDb

    -

    ​
    Make sure it’s running
    ​Example

    The following agent will run seach Zendesk for “How do I login?” and print the response.

    cookbook/tools/zendesk_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    username

    str

    -

    The username used for authentication or identification purposes.

    password

    str

    -

    The password associated with the username for authentication purposes.

    company_name

    str

    -

    ​Toolkit Functions

    Function
    Description

    search_zendesk

    This function searches for articles in Zendesk Help Center that match the given search string.

    ​

    Prompts

    We prompt Agents using description and instructions and a number of other settings. These settings are used to build the system prompt that is sent to the language model.

    Understanding how these prompts are created will help you build better Agents.

    The 2 key parameters are:

    1. Description: A description that guides the overall behaviour of the agent.

    2. Instructions: A list of precise, task-specific instructions on how to achieve its goal.

    System message

    The system message is created using description, instructions and a number of other settings. The description is added to the start of the system message and instructions are added as a list after ## Instructions. For example:

    instructions.py

    Will translate to (set debug_mode=True to view the logs):

    Set the system message directly

    You can manually set the system message using the system_prompt parameter.

    User message

    The input message sent to the Agent.run() or Agent.print_response() functions is used as the user message.

    User message when enable_rag=True

    If the Agent is provided knowledge, and the enable_rag=True, the user message is set to:

    Default system message

    The Agent creates a default system message that can be customized using the following parameters:

    Parameter
    Type
    Default
    Description

    Default user message

    The Agent creates a default user message, which is either the input message or a message with the context if enable_rag=True. The default user message can be customized using:

    Parameter
    Type
    Default
    Description

    Searxng

    Example

    Searxng enables an Agent to search the web for a query, scrape a website, or crawl a website.

    cookbook/tools/searxng_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    Toolkit Functions

    Function
    Description

    Combined KnowledgeBase

    The CombinedKnowledgeBase combines multiple knowledge bases into 1 and is used when your app needs information using multiple sources.

    ​Usage

    We are using a local PgVector database for this example. Make sure it’s running

    pip install pypdf bs4

    knowledge_base.py

    Then use the knowledge_base with an Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    CSV Knowledge Base

    The CSVKnowledgeBase reads local CSV files, converts them into vector embeddings and loads them to a vector databse.

    ​Usage

    We are using a local PgVector database for this example. Make sure it’s running

    from bitca.knowledge.csv import CSVKnowledgeBase
    from bitca.vectordb.pgvector import PgVector
    
    knowledge_base = CSVKnowledgeBase(
        path="data/csv",
        # Table name: ai.csv_documents
        vector_db=PgVector(
            table_name="csv_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )

    Then use the knowledge_base with an Agent:

    Params

    Parameter
    Type
    Default
    Description

    ArXiv Knowledge Base

    The ArxivKnowledgeBase reads Arxiv articles, converts them into vector embeddings and loads them to a vector databse.

    ​Usage

    We are using a local PgVector database for this example. Make sure it’s running

    pip install arxiv

    knowledge_base.py

    Then use the knowledge_base with an Agent:

    agent.py

    Params

    Parameter
    Type
    Default
    Description

    Open AI

    The GPT models are the best in class LLMs and used as the default LLM by Agents.

    Authentication

    Set your OPENAI_API_KEY environment variable. You can get one .

    MacWindows

    Memory

    Bitca provides 3 types of memories for building a great Agent experience (AX):

    1. Chat History: previous messages from the conversation, we recommend sending the last 3-5 messages to the model.

    2. User Memories: notes and insights about the user, this helps the model personalize the response to the user.

    3. Summaries: a summary of the conversation, which is added to the prompt when chat history gets too long.

    Before we dive in, let’s understand the terminology:

    SQL

    SQLTools enable an Agent to run SQL queries and interact with databases.

    Prerequisites

    The following example requires the sqlalchemy library and a database URL.

    You will also need a database. The following example uses a Postgres database running in a Docker container.

    Twitter

    Prerequisites

    The following example requires the tweepy library.

    Get a Twitter API key and secret from .

    pip install -U pgvector pypdf "psycopg[binary]" sqlalchemy
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.knowledge.pdf import PDFUrlKnowledgeBase
    from bitca.vectordb.pgvector import PgVector, SearchType
    
    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    knowledge_base = PDFUrlKnowledgeBase(
        # Read PDF from this URL
        urls=["https://bitca-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
        # Store embeddings in the `ai.recipes` table
        vector_db=PgVector(table_name="recipes", db_url=db_url, search_type=SearchType.hybrid),
    )
    # Load the knowledge base: Comment after first run
    knowledge_base.load(upsert=True)
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        knowledge=knowledge_base,
        # Enable RAG by adding references from AgentKnowledge to the user prompt.
        add_context=True,
        # Set as False because Agents default to `search_knowledge=True`
        search_knowledge=False,
        markdown=True,
        # debug_mode=True,
    )
    agent.print_response("How do I make chicken and galangal in coconut milk soup"
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.knowledge.pdf import PDFUrlKnowledgeBase
    from bitca.vectordb.pgvector import PgVector, SearchType
    
    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    knowledge_base = PDFUrlKnowledgeBase(
        urls=["https://bitca-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
        vector_db=PgVector(table_name="recipes", db_url=db_url, search_type=SearchType.hybrid),
    )
    # Load the knowledge base: Comment out after first run
    knowledge_base.load(upsert=True)
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        knowledge=knowledge_base,
        # Add a tool to search the knowledge base which enables agentic RAG.
        search_knowledge=True,
        # Add a tool to read chat history.
        read_chat_history=True,
        show_tool_calls=True,
        markdown=True,
        # debug_mode=True,
    )
    agent.print_response("How do I make chicken and galangal in coconut milk soup", stream=True)
    agent.print_response("What was my last question?", markdown=True)
    python agentic_rag.py
    from bitca.agent import Agent, AgentKnowledge
    
    # Create a knowledge base for the Agent
    knowledge_base = AgentKnowledge(vector_db=...)
    
    # Add information to the knowledge base
    knowledge_base.load_text("The sky is blue")
    
    # Add the knowledge base to the Agent and
    # give it a tool to search the knowledge base as needed
    agent = Agent(knowledge=knowledge_base, search_knowledge=True)
    docker run -d \
      -e POSTGRES_DB=ai \
      -e POSTGRES_USER=ai \
      -e POSTGRES_PASSWORD=ai \
      -e PGDATA=/var/lib/postgresql/data/pgdata \
      -v pgvolume:/var/lib/postgresql/data \
      -p 5532:5432 \
      --name pgvector \
      bitca/pgvector:16
    export HF_TOKEN=***
    from bitca.agent import Agent, RunResponse
    from bitca.model.huggingface import HuggingFaceChat
    
    agent = Agent(
        model=HuggingFaceChat(
            id="meta-llama/Meta-Llama-3-8B-Instruct",
            max_tokens=4096,
        ),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response on the terminal
    agent.print_response("Share a 2 sentence horror story.")
    export MISTRAL_API_KEY=***
    import os
    
    from bitca.agent import Agent, RunResponse
    from bitca.model.mistral import MistralChat
    
    mistral_api_key = os.getenv("MISTRAL_API_KEY")
    
    agent = Agent(
        model=MistralChat(
            id="mistral-large-latest",
            api_key=mistral_api_key,
        ),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    export GROQ_API_KEY=***
    from bitca.agent import Agent, RunResponse
    from bitca.model.groq import Groq
    
    agent = Agent(
        model=Groq(id="llama-3.3-70b-versatile"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    pip install mlx-whisper
    
    from pathlib import Path
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.mlx_transcribe import MLXTranscribe
    
    # Get audio files from storage/audio directory
    bitca_root_dir = Path(__file__).parent.parent.parent.resolve()
    audio_storage_dir = bitca_root_dir.joinpath("storage/audio")
    if not audio_storage_dir.exists():
        audio_storage_dir.mkdir(exist_ok=True, parents=True)
    
    agent = Agent(
        name="Transcription Agent",
        model=OpenAIChat(id="gpt-4o"),
        tools=[MLXTranscribe(base_dir=audio_storage_dir)],
        instructions=[
            "To transcribe an audio file, use the `transcribe` tool with the name of the audio file as the argument.",
            "You can find all available audio files using the `read_files` tool.",
        ],
        markdown=True,
    )
    
    agent.print_response("Summarize the reid hoffman ted talk, split into sections", stream=True)
    
    pip install -U psycopg2
    docker run -d \
      -e POSTGRES_DB=ai \
      -e POSTGRES_USER=ai \
      -e POSTGRES_PASSWORD=ai \
      -e PGDATA=/var/lib/postgresql/data/pgdata \
      -v pgvolume:/var/lib/postgresql/data \
      -p 5532:5432 \
      --name pgvector \
      bitca/pgvector:16
    from bitca.agent import Agent
    from bitca.tools.postgres import PostgresTools
    
    # Initialize PostgresTools with connection details
    postgres_tools = PostgresTools(
        host="localhost",
        port=5532,
        db_name="ai",
        user="ai", 
        password="ai"
    )
    
    # Create an agent with the PostgresTools
    agent = Agent(tools=[postgres_tools])
    
    # Example: Ask the agent to run a SQL query
    agent.print_response("""
    Please run a SQL query to get all users from the users table 
    who signed up in the last 30 days
    """)
    from bitca.knowledge.pdf import PDFUrlKnowledgeBase
    from bitca.vectordb.pgvector import PgVector
    
    knowledge_base = CSVUrlKnowledgeBase(
        urls=["csv_url"],
        # Table name: ai.csv_documents
        vector_db=PgVector(
            table_name="csv_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )
    from bitca.agent import Agent
    from knowledge_base import knowledge_base
    
    agent = Agent(
        knowledge=knowledge_base,
        search_knowledge=True,
    )
    agent.knowledge.load(recreate=False)
    
    agent.print_response("Ask me about something from the knowledge base")
    pip install -U requests
    export ZENDESK_USERNAME=***
    export ZENDESK_PW=***
    export ZENDESK_COMPANY_NAME=***
    from bitca.agent import Agent
    from bitca.tools.zendesk import ZendeskTools
    
    agent = Agent(tools=[ZendeskTools()], show_tool_calls=True)
    agent.print_response("How do I login?", markdown=True)
    from bitca.agent import Agent
    from bitca.tools.searxng import Searxng
    
    # Initialize Searxng with your Searxng instance URL
    searxng = Searxng(
        host="http://localhost:53153",
        engines=[],
        fixed_max_results=5,
        news=True,
        science=True
    )
    
    # Create an agent with Searxng
    agent = Agent(tools=[searxng])
    
    # Example: Ask the agent to search using Searxng
    agent.print_response("""
    Please search for information about artificial intelligence
    and summarize the key points from the top results
    """)
    from bitca.knowledge.combined import CombinedKnowledgeBase
    from bitca.vectordb.pgvector import PgVector
    
    url_pdf_knowledge_base = PDFUrlKnowledgeBase(
        urls=["pdf_url"],
        # Table name: ai.pdf_documents
        vector_db=PgVector(
            table_name="pdf_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )
    
    website_knowledge_base = WebsiteKnowledgeBase(
        urls=["https://docs.bitcadata.com/introduction"],
        # Number of links to follow from the seed URLs
        max_links=10,
        # Table name: ai.website_documents
        vector_db=PgVector(
            table_name="website_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )
    
    local_pdf_knowledge_base = PDFKnowledgeBase(
        path="data/pdfs",
        # Table name: ai.pdf_documents
        vector_db=PgVector(
            table_name="pdf_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
        reader=PDFReader(chunk=True),
    )
    
    knowledge_base = CombinedKnowledgeBase(
        sources=[
            url_pdf_knowledge_base,
            website_knowledge_base,
            local_pdf_knowledge_base,
        ],
        vector_db=PgVector(
            # Table name: ai.combined_documents
            table_name="combined_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )
    from bitca.agent import Agent
    from knowledge_base import knowledge_base
    
    agent = Agent(
        knowledge=knowledge_base,
        search_knowledge=True,
    )
    agent.knowledge.load(recreate=False)
    
    agent.print_response("Ask me about something from the knowledge base")
    from bitca.agent import Agent
    from knowledge_base import knowledge_base
    
    agent = Agent(
        knowledge=knowledge_base,
        search_knowledge=True,
    )
    agent.knowledge.load(recreate=False)
    
    agent.print_response("Ask me about something from the knowledge base")
    from bitca.knowledge.arxiv import ArxivKnowledgeBase
    from bitca.vectordb.pgvector import PgVector
    
    knowledge_base = ArxivKnowledgeBase(
        queries=["Generative AI", "Machine Learning"],
        # Table name: ai.arxiv_documents
        vector_db=PgVector(
            table_name="arxiv_documents",
            db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        ),
    )

    The provider of the model.

    store

    Optional[bool]

    -

    Whether or not to store the output of this chat completion request.

    frequency_penalty

    Optional[float]

    -

    Penalizes new tokens based on their frequency in the text so far.

    logit_bias

    Optional[Any]

    -

    Modifies the likelihood of specified tokens appearing in the completion.

    logprobs

    Optional[bool]

    -

    Include the log probabilities on the logprobs most likely tokens.

    max_tokens

    Optional[int]

    -

    The maximum number of tokens to generate in the chat completion.

    presence_penalty

    Optional[float]

    -

    Penalizes new tokens based on whether they appear in the text so far.

    response_format

    Optional[Any]

    -

    An object specifying the format that the model must output.

    seed

    Optional[int]

    -

    A seed for deterministic sampling.

    stop

    Optional[Union[str, List[str]]]

    -

    Up to 4 sequences where the API will stop generating further tokens.

    temperature

    Optional[float]

    -

    Controls randomness in the model's output.

    top_logprobs

    Optional[int]

    -

    How many log probability results to return per token.

    top_p

    Optional[float]

    -

    Controls diversity via nucleus sampling.

    request_params

    Optional[Dict[str, Any]]

    -

    Additional parameters to include in the request.

    api_key

    Optional[str]

    -

    The Access Token for authenticating with HuggingFace.

    base_url

    Optional[Union[str, httpx.URL]]

    -

    The base URL for API requests.

    timeout

    Optional[float]

    -

    The timeout for API requests.

    max_retries

    Optional[int]

    -

    The maximum number of retries for failed requests.

    default_headers

    Optional[Any]

    -

    Default headers to include in all requests.

    default_query

    Optional[Any]

    -

    Default query parameters to include in all requests.

    http_client

    Optional[httpx.Client]

    -

    An optional pre-configured HTTP client.

    client_params

    Optional[Dict[str, Any]]

    -

    Additional parameters for client configuration.

    client

    Optional[InferenceClient]

    -

    The HuggingFace Hub Inference client instance.

    async_client

    Optional[AsyncInferenceClient]

    -

    The asynchronous HuggingFace Hub client instance.

    The provider of the model.

    temperature

    Optional[float]

    None

    Controls randomness in output generation.

    max_tokens

    Optional[int]

    None

    Maximum number of tokens to generate.

    top_p

    Optional[float]

    None

    Controls diversity of output generation.

    random_seed

    Optional[int]

    None

    Seed for random number generation.

    safe_mode

    bool

    False

    Enables content filtering.

    safe_prompt

    bool

    False

    Applies content filtering to prompts.

    response_format

    Optional[Union[Dict[str, Any], ChatCompletionResponse]]

    None

    Specifies the desired response format.

    request_params

    Optional[Dict[str, Any]]

    None

    Additional request parameters.

    api_key

    Optional[str]

    None

    Your Mistral API key.

    endpoint

    Optional[str]

    None

    Custom API endpoint URL.

    max_retries

    Optional[int]

    None

    Maximum number of API call retries.

    timeout

    Optional[int]

    None

    Timeout for API calls in seconds.

    client_params

    Optional[Dict[str, Any]]

    None

    Additional client parameters.

    mistral_client

    Optional[Mistral]

    None

    Custom Mistral client instance.

    The provider of the model.

    frequency_penalty

    Optional[float]

    -

    A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.

    logit_bias

    Optional[Any]

    -

    A JSON object that modifies the likelihood of specified tokens appearing in the completion by mapping token IDs to bias values between -100 and 100.

    logprobs

    Optional[bool]

    -

    Whether to return log probabilities of the output tokens.

    max_tokens

    Optional[int]

    -

    The maximum number of tokens to generate in the chat completion.

    presence_penalty

    Optional[float]

    -

    A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

    response_format

    Optional[Dict[str, Any]]

    -

    Specifies the format that the model must output. Setting to { "type": "json_object" } enables JSON mode, ensuring the message generated is valid JSON.

    seed

    Optional[int]

    -

    A seed value for deterministic sampling, ensuring repeated requests with the same seed and parameters return the same result.

    stop

    Optional[Union[str, List[str]]]

    -

    Up to 4 sequences where the API will stop generating further tokens.

    temperature

    Optional[float]

    -

    The sampling temperature to use, between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic.

    top_logprobs

    Optional[int]

    -

    The number of top log probabilities to return for each generated token.

    top_p

    Optional[float]

    -

    Nucleus sampling parameter. The model considers the results of the tokens with top_p probability mass.

    user

    Optional[str]

    -

    A unique identifier representing your end-user, helping to monitor and detect abuse.

    request_params

    Optional[Dict[str, Any]]

    -

    Additional parameters to include in the request.

    api_key

    Optional[str]

    -

    The API key for authenticating requests to the service.

    base_url

    Optional[Union[str, httpx.URL]]

    -

    The base URL for making API requests to the service.

    timeout

    Optional[int]

    -

    The timeout duration for requests, specified in seconds.

    max_retries

    Optional[int]

    -

    The maximum number of retry attempts for failed requests.

    client_params

    Optional[Dict[str, Any]]

    -

    Additional parameters for client configuration.

    groq_client

    Optional[GroqClient]

    -

    An instance of GroqClient provided for making API requests.

    Path or HuggingFace repo for the model

    verbose

    bool

    None

    Enable verbose output

    temperature

    float or Tuple[float, ...]

    None

    Temperature for sampling

    compression_ratio_threshold

    float

    None

    Compression ratio threshold

    logprob_threshold

    float

    None

    Log probability threshold

    no_speech_threshold

    float

    None

    No speech threshold

    condition_on_previous_text

    bool

    None

    Whether to condition on previous text

    initial_prompt

    str

    None

    Initial prompt for transcription

    word_timestamps

    bool

    None

    Enable word-level timestamps

    prepend_punctuations

    str

    None

    Punctuations to prepend

    append_punctuations

    str

    None

    Punctuations to append

    clip_timestamps

    str or List[float]

    None

    Clip timestamps

    hallucination_silence_threshold

    float

    None

    Hallucination silence threshold

    decode_options

    dict

    None

    Additional decoding options

    Optional username for database authentication.

    password

    str

    None

    Optional password for database authentication.

    host

    str

    None

    Optional host for the database connection.

    port

    int

    None

    Optional port for the database connection.

    run_queries

    bool

    True

    Enables running SQL queries.

    inspect_queries

    bool

    False

    Enables inspecting SQL queries before execution.

    summarize_tables

    bool

    True

    Enables summarizing table structures.

    export_tables

    bool

    False

    Enables exporting tables from the database.

    Vector Database for the Knowledge Base.

    num_documents

    int

    5

    Number of documents to return on search.

    optimize_on

    int

    -

    Number of documents to optimize the vector db on.

    chunking_strategy

    ChunkingStrategy

    FixedSizeChunking

    The chunking strategy to use.

    The name of the company related to the user or the data being accessed.

    images

    bool

    False

    Enables searching for images.

    it

    bool

    False

    Enables searching for IT-related content.

    map

    bool

    False

    Enables searching for maps.

    music

    bool

    False

    Enables searching for music.

    news

    bool

    False

    Enables searching for news.

    science

    bool

    False

    Enables searching for science-related content.

    videos

    bool

    False

    Enables searching for videos.

    science_search

    Performs a search for science-related information using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the science search results.

    video_search

    Performs a search for videos using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the video search results.

    host

    str

    -

    The host for the connection.

    engines

    List[str]

    []

    A list of search engines to use.

    fixed_max_results

    int

    None

    search

    Performs a general web search using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the search results.

    image_search

    Performs an image search using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the image search results.

    it_search

    Performs a search for IT-related information using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the IT-related search results.

    map_search

    Performs a search for maps using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the map search results.

    music_search

    Performs a search for music-related information using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the music search results.

    news_search

    Performs a search for news using the specified query. Parameters include query for the search term and max_results for the maximum number of results (default is 5). Returns the news search results.

    ​

    Optional parameter to specify the fixed maximum number of results.

    num_documents

    int

    5

    Number of documents to return on search.

    optimize_on

    int

    -

    Number of documents to optimize the vector db on.

    chunking_strategy

    ChunkingStrategy

    FixedSizeChunking

    The chunking strategy to use.

    sources

    List[AgentKnowledge]

    -

    List of Agent knowledge bases.

    reader

    Reader

    -

    A Reader that converts the content of the documents into Documents for the vector database.

    vector_db

    VectorDb

    -

    ​

    Vector Database for the Knowledge Base.

    num_documents

    int

    5

    Number of documents to return on search.

    optimize_on

    int

    -

    Number of documents to optimize the vector db on.

    chunking_strategy

    ChunkingStrategy

    FixedSizeChunking

    The chunking strategy to use.

    path

    Union[str, Path]

    -

    Path to docx files. Can point to a single docx file or a directory of docx files.

    reader

    CSVReader

    CSVReader()

    A CSVReader that converts the CSV files into Documents for the vector database.

    vector_db

    VectorDb

    -

    ​

    Vector Database for the Knowledge Base.

    Enable RAG by adding references from AgentKnowledge to the user prompt.

    retriever

    Callable[..., Optional[list[dict]]]

    None

    Function to get context to add to the user message. This function is called when add_context is True.

    context_format

    Literal['json', 'yaml']

    json

    Specifies the format for RAG, either “json” or “yaml”.

    add_context_instructions

    bool

    False

    If True, add instructions for using the context to the system prompt (if knowledge is also provided). For example: add an instruction to prefer information from the knowledge base over its training data.

    additional_context

    str

    None

    Additional context added to the end of the system message.

    expected_output

    str

    None

    Provide the expected output from the Agent. This is added to the end of the system message.

    extra_instructions

    List[str]

    None

    List of extra instructions added to the default system prompt. Use these when you want to add some extra instructions at the end of the default instructions.

    prevent_hallucinations

    bool

    False

    If True, add instructions to return “I don’t know” when the agent does not know the answer.

    prevent_prompt_injection

    bool

    False

    If True, add instructions to prevent prompt injection attacks.

    limit_tool_access

    bool

    False

    If True, add instructions for limiting tool access to the default system prompt if tools are provided

    markdown

    bool

    False

    Add an instruction to format the output using markdown.

    add_datetime_to_instructions

    bool

    False

    If True, add the current datetime to the prompt to give the agent a sense of time. This allows for relative times like “tomorrow” to be used in the prompt

    system_prompt

    str

    None

    System prompt: provide the system prompt as a string

    system_prompt_template

    PromptTemplate

    None

    Provide the system prompt as a PromptTemplate.

    use_default_system_message

    bool

    True

    If True, build a default system message using agent settings and use that.

    system_message_role

    str

    system

    Role for the system message.

    num_history_responses

    int

    3

    Number of historical responses to add to the messages.

    user_prompt

    Union[List, Dict, str]

    None

    Provide the user prompt as a string. Note: this will ignore the message sent to the run function.

    user_prompt_template

    PromptTemplate

    None

    Provide the user prompt as a PromptTemplate.

    use_default_user_message

    bool

    True

    If True, build a default user prompt using references and chat history.

    user_message_role

    str

    user

    Role for the user message.

    description

    str

    None

    A description of the Agent that is added to the start of the system message.

    task

    str

    None

    Describe the task the agent should achieve.

    instructions

    List[str]

    None

    enable_rag

    bool

    False

    Enable RAG by adding references from the knowledge base to the prompt.

    add_rag_instructions

    bool

    False

    If True, adds instructions for using the RAG to the system prompt (if knowledge is also provided). For example: add an instruction to prefer information from the knowledge base over its training data.

    add_history_to_messages

    bool

    False

    List of instructions added to the system prompt in <instructions> tags. Default instructions are also created depending on values for markdown, output_model etc.

    If true, adds the chat history to the messages sent to the Model.

    num_documents

    int

    5

    Number of documents to return on search.

    optimize_on

    int

    -

    Number of documents to optimize the vector db on.

    chunking_strategy

    ChunkingStrategy

    FixedSizeChunking

    The chunking strategy to use.

    queries

    List[str]

    -

    Queries to search

    reader

    ArxivReader

    ArxivReader()

    A ArxivReader that reads the articles and converts them into Documents for the vector database.

    vector_db

    VectorDb

    -

    ​

    Vector Database for the Knowledge Base.

    python traditional_rag.py
    from bitca.agent import Agent
    
    agent = Agent(
        description="You are a famous short story writer asked to write for a magazine",
        instructions=["You are a pilot on a plane flying from Hawaii to Japan."],
        markdown=True,
        debug_mode=True,
    )
    agent.print_response("Tell me a 2 sentence horror story.", stream=True)
    DEBUG    ============== system ==============
    DEBUG    You are a famous short story writer asked to write for a magazine
    
             ## Instructions
             - You are a pilot on a plane flying from Hawaii to Japan.
             - Use markdown to format your answers.
    DEBUG    ============== user ==============
    DEBUG    Tell me a 2 sentence horror story.
    DEBUG    ============== assistant ==============
    DEBUG    As the autopilot disengaged inexplicably mid-flight over the Pacific, the pilot glanced at the copilot's seat
             only to find it empty despite his every recall of a full crew boarding. Hands trembling, he looked into the
             cockpit's rearview mirror and found his own reflection grinning back with blood-red eyes, whispering,
             "There's no escape, not at 30,000 feet."
    DEBUG    **************** METRICS START ****************
    DEBUG    * Time to first token:         0.4518s
    DEBUG    * Time to generate response:   1.2594s
    DEBUG    * Tokens per second:           63.5243 tokens/s
    DEBUG    * Input tokens:                59
    DEBUG    * Output tokens:               80
    DEBUG    * Total tokens:                139
    DEBUG    * Prompt tokens details:       {'cached_tokens': 0}
    DEBUG    * Completion tokens details:   {'reasoning_tokens': 0}
    DEBUG    **************** METRICS END ******************
    from bitca.agent import Agent
    
    agent = Agent(system_prompt="Share a 2 sentence story about")
    agent.print_response("Love in the year 12000.")
    user_prompt += f"""Use the following information from the knowledge base if it helps:"
    
    ## Context
    {context}
    """
    from bitca.agent import Agent
    from knowledge_base import knowledge_base
    
    agent = Agent(
        knowledge=knowledge_base,
        search_knowledge=True,
    )
    agent.knowledge.load(recreate=False)
    
    agent.print_response("Ask me about something from the knowledge base")
    ​Example

    Use OpenAIChat with your Agent:

    agent.py

    ​Params

    For more information, please refer to the OpenAI docs as well.

    Name
    Type
    Default
    Description

    id

    str

    "gpt-4o"

    The id of the OpenAI model to use.

    name

    str

    "OpenAIChat"

    The name of this chat model instance.

    provider

    str

    "OpenAI " + id

    ​
    from OpenAI here
  • Session: Each conversation with an Agent is called a session. Sessions are identified by a session_id.

  • Run: Every interaction (i.e. chat) within a session is called a run. Runs are identified by a run_id.

  • Messages: are the individual messages sent to and received from the model. They have a role (system, user or assistant) and content.

  • Built-in Memory

    Every Agent comes with built-in memory that can be used to access the historical runs and messages. Access it using agent.memory

    runslist[AgentRun]

    The list of runs between the user and agent. Each run contains the input message and output response.

    ​messageslist[Message]

    The full list of messages sent to the model, including system prompt, tool calls etc.

    Example

    agent_memory.py

    Persistent Memory

    The built-in memory only lasts while the session is active. To persist memory across sessions, we can store Agent sessions in a database using AgentStorage.

    Storage is a necessary component when building user facing AI products as any production application will require users to be able to “continue” their conversation with the Agent.

    Let’s test this out, create a file persistent_memory.py with the following code:

    persistent_memory.py

    Run the agent

    Install dependencies and run the agent:

    You can view the agent sessions in the sqlite database and continue any conversation by providing the same session_id.

    Read more in the storage section.

    User preferences and conversation summaries

    Along with storing chat history and run messages, AgentMemory can be extended to automatically classify and store user preferences and conversation summaries.

    To do this, add a db to AgentMemory and set create_user_memories=True and create_session_summary=True

    User memories are stored in the AgentMemory whereas session summaries are stored in the AgentStorage table with the rest of the session information.

    Example

    personalized_memories_and_summaries.py

    Attributes

    Parameter
    Type
    Default
    Description

    memory

    AgentMemory

    AgentMemory()

    Agent’s memory object used for storing and retrieving information.

    add_history_to_messages

    bool

    False

    If true, adds the chat history to the messages sent to the Model. Also known as add_chat_history_to_messages.

    num_history_responses

    int

    3

    ​Example

    The following agent will run a SQL query to list all tables in the database and describe the contents of one of the tables.

    cookbook/tools/sql_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    db_url

    str

    -

    The URL for connecting to the database.

    db_engine

    Engine

    -

    The database engine used for connections and operations.

    user

    str

    -

    ​Toolkit Functions

    Function
    Description

    list_tables

    Lists all tables in the database.

    describe_table

    Describes the schema of a specific table.

    run_sql_query

    Executes SQL queries directly.

    ​
    ​Example

    The following agent will use Twitter to get information about a user, send a message to a user, and create a new tweet.

    cookbook/tools/twitter_tools.py

    ​Toolkit Params

    Parameter
    Type
    Default
    Description

    bearer_token

    str

    None

    The bearer token for Twitter API authentication

    consumer_key

    str

    None

    The consumer key for Twitter API authentication

    consumer_secret

    str

    None

    ​Toolkit Functions

    Function
    Description

    create_tweet

    Creates and posts a new tweet

    reply_to_tweet

    Replies to an existing tweet

    send_dm

    Sends a direct message to a Twitter user

    get_user_info

    Retrieves information about a Twitter user

    get_home_timeline

    Gets the authenticated user’s home timeline

    here
    export OPENAI_API_KEY=sk-***
    
    from bitca.agent import Agent, RunResponse
    from bitca.model.openai import OpenAIChat
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        markdown=True
    )
    
    # Get the response in a variable
    # run: RunResponse = agent.run("Share a 2 sentence horror story.")
    # print(run.content)
    
    # Print the response in the terminal
    agent.print_response("Share a 2 sentence horror story.")
    
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from rich.pretty import pprint
    
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        # Set add_history_to_messages=true to add the previous chat history to the messages sent to the Model.
        add_history_to_messages=True,
        # Number of historical responses to add to the messages.
        num_history_responses=3,
        description="You are a helpful assistant that always responds in a polite, upbeat and positive manner.",
    )
    
    # -*- Create a run
    agent.print_response("Share a 2 sentence horror story", stream=True)
    # -*- Print the messages in the memory
    pprint([m.model_dump(include={"role", "content"}) for m in agent.memory.messages])
    
    # -*- Ask a follow up question that continues the conversation
    agent.print_response("What was my first message?", stream=True)
    # -*- Print the messages in the memory
    pprint([m.model_dump(include={"role", "content"}) for m in agent.memory.messages])
    import json
    
    from rich.console import Console
    from rich.panel import Panel
    from rich.json import JSON
    
    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.storage.agent.sqlite import SqlAgentStorage
    
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        # Store agent sessions in a database
        storage=SqlAgentStorage(table_name="agent_sessions", db_file="tmp/agent_storage.db"),
        # Set add_history_to_messages=true to add the previous chat history to the messages sent to the Model.
        add_history_to_messages=True,
        # Number of historical responses to add to the messages.
        num_history_responses=3,
        # The session_id is used to identify the session in the database
        # You can resume any session by providing a session_id
        # session_id="xxxx-xxxx-xxxx-xxxx",
        # Description creates a system prompt for the agent
        description="You are a helpful assistant that always responds in a polite, upbeat and positive manner.",
    )
    
    console = Console()
    
    
    def print_chat_history(agent):
        # -*- Print history
        console.print(
            Panel(
                JSON(json.dumps([m.model_dump(include={"role", "content"}) for m in agent.memory.messages]), indent=4),
                title=f"Chat History for session_id: {agent.session_id}",
                expand=True,
            )
        )
    
    
    # -*- Create a run
    agent.print_response("Share a 2 sentence horror story", stream=True)
    # -*- Print the chat history
    print_chat_history(agent)
    
    # -*- Ask a follow up question that continues the conversation
    agent.print_response("What was my first message?", stream=True)
    # -*- Print the chat history
    print_chat_history(agent)
    pip install openai sqlalchemy bitca
    
    python persistent_memory.py
    from rich.pretty import pprint
    
    from bitca.agent import Agent, AgentMemory
    from bitca.model.openai import OpenAIChat
    from bitca.memory.db.postgres import PgMemoryDb
    from bitca.storage.agent.postgres import PgAgentStorage
    
    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        # Store the memories and summary in a database
        memory=AgentMemory(
            db=PgMemoryDb(table_name="agent_memory", db_url=db_url), create_user_memories=True, create_session_summary=True
        ),
        # Store agent sessions in a database
        storage=PgAgentStorage(table_name="personalized_agent_sessions", db_url=db_url),
        # Show debug logs so you can see the memory being created
        # debug_mode=True,
    )
    
    # -*- Share personal information
    agent.print_response("My name is john billings?", stream=True)
    # -*- Print memories
    pprint(agent.memory.memories)
    # -*- Print summary
    pprint(agent.memory.summary)
    
    # -*- Share personal information
    agent.print_response("I live in nyc?", stream=True)
    # -*- Print memories
    pprint(agent.memory.memories)
    # -*- Print summary
    pprint(agent.memory.summary)
    
    # -*- Share personal information
    agent.print_response("I'm going to a concert tomorrow?", stream=True)
    # -*- Print memories
    pprint(agent.memory.memories)
    # -*- Print summary
    pprint(agent.memory.summary)
    
    # Ask about the conversation
    agent.print_response("What have we been talking about, do you know my name?", stream=
    pip install -U sqlalchemy
     docker run -d \
      -e POSTGRES_DB=ai \
      -e POSTGRES_USER=ai \
      -e POSTGRES_PASSWORD=ai \
      -e PGDATA=/var/lib/postgresql/data/pgdata \
      -v pgvolume:/var/lib/postgresql/data \
      -p 5532:5432 \
      --name pgvector \
      bitca/pgvector:16
    from bitca.agent import Agent
    from bitca.tools.sql import SQLTools
    
    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    
    agent = Agent(tools=[SQLTools(db_url=db_url)])
    agent.print_response("List the tables in the database. Tell me about contents of one of the tables", markdown=True)
    pip install tweepy
    export TWITTER_CONSUMER_KEY=***
    export TWITTER_CONSUMER_SECRET=***
    export TWITTER_ACCESS_TOKEN=***
    export TWITTER_ACCESS_TOKEN_SECRET=***
    export TWITTER_BEARER_TOKEN=***
    from bitca.agent import Agent
    from bitca.tools.twitter import TwitterTools
    
    # Initialize the Twitter toolkit
    twitter_tools = TwitterTools()
    
    # Create an agent with the twitter toolkit
    agent = Agent(
        instructions=[
            "Use your tools to interact with Twitter as the authorized user @bitca",
            "When asked to create a tweet, generate appropriate content based on the request",
            "Do not actually post tweets unless explicitly instructed to do so",
            "Provide informative responses about the user's timeline and tweets",
            "Respect Twitter's usage policies and rate limits",
        ],
        tools=[twitter_tools],
        show_tool_calls=True,
    )
    agent.print_response("Can you retrieve information about this user https://x.com/bitca", markdown=True)
    
    # Example usage: Reply To a Tweet
    agent.print_response(
        "Can you reply to this post as a general message as to how great this project is:https://x.com/bitca",
        markdown=True,
    )
    # Example usage: Get your details
    agent.print_response("Can you return my twitter profile?", markdown=True)
    
    # Example usage: Send a direct message
    agent.print_response(
        "Can a send direct message to the user: https://x.com/bitca assking you want learn more about them and a link to their community?",
        markdown=True,
    )
    # Example usage: Create a new tweet
    agent.print_response("Create & post a tweet about the importance of AI ethics", markdown=True)
    
    # Example usage: Get home timeline
    agent.print_response("Get my timeline", markdown=True)
    

    The provider of the model.

    store

    Optional[bool]

    None

    Whether or not to store the output of this chat completion request for use in the model distillation or evals products.

    frequency_penalty

    Optional[float]

    None

    Penalizes new tokens based on their frequency in the text so far.

    logit_bias

    Optional[Any]

    None

    Modifies the likelihood of specified tokens appearing in the completion.

    logprobs

    Optional[bool]

    None

    Include the log probabilities on the logprobs most likely tokens.

    max_tokens

    Optional[int]

    None

    The maximum number of tokens to generate in the chat completion.

    presence_penalty

    Optional[float]

    None

    Penalizes new tokens based on whether they appear in the text so far.

    response_format

    Optional[Any]

    None

    An object specifying the format that the model must output.

    seed

    Optional[int]

    None

    A seed for deterministic sampling.

    stop

    Optional[Union[str, List[str]]]

    None

    Up to 4 sequences where the API will stop generating further tokens.

    temperature

    Optional[float]

    None

    Controls randomness in the model's output.

    top_logprobs

    Optional[int]

    None

    How many log probability results to return per token.

    user

    Optional[str]

    None

    A unique identifier representing your end-user.

    top_p

    Optional[float]

    None

    Controls diversity via nucleus sampling.

    extra_headers

    Optional[Any]

    None

    Additional headers to send with the request.

    extra_query

    Optional[Any]

    None

    Additional query parameters to send with the request.

    request_params

    Optional[Dict[str, Any]]

    None

    Additional parameters to include in the request.

    api_key

    Optional[str]

    None

    The API key for authenticating with OpenAI.

    organization

    Optional[str]

    None

    The organization to use for API requests.

    base_url

    Optional[Union[str, httpx.URL]]

    None

    The base URL for API requests.

    timeout

    Optional[float]

    None

    The timeout for API requests.

    max_retries

    Optional[int]

    None

    The maximum number of retries for failed requests.

    default_headers

    Optional[Any]

    None

    Default headers to include in all requests.

    default_query

    Optional[Any]

    None

    Default query parameters to include in all requests.

    http_client

    Optional[httpx.Client]

    None

    An optional pre-configured HTTP client.

    client_params

    Optional[Dict[str, Any]]

    None

    Additional parameters for client configuration.

    client

    Optional[OpenAIClient]

    None

    The OpenAI client instance.

    async_client

    Optional[AsyncOpenAIClient]

    None

    The asynchronous OpenAI client instance.

    structured_outputs

    bool

    False

    Whether to use the structured outputs from the Model.

    supports_structured_outputs

    bool

    True

    Whether the Model supports structured outputs.

    add_images_to_message_content

    bool

    True

    Whether to add images to the message content.

    Number of historical responses to add to the messages.

    create_user_memories

    bool

    False

    If true, create and store personalized memories for the user.

    update_user_memories_after_run

    bool

    True

    If true, update memories for the user after each run.

    create_session_summary

    bool

    False

    If true, create and store session summaries.

    update_session_summary_after_run

    bool

    True

    If true, update session summaries after each run.

    The username for database authentication.

    password

    str

    -

    The password for database authentication.

    host

    str

    -

    The hostname or IP address of the database server.

    port

    int

    -

    The port number on which the database server is listening.

    schema

    str

    -

    The specific schema within the database to use.

    dialect

    str

    -

    The SQL dialect used by the database.

    tables

    Dict[str, Any]

    -

    A dictionary mapping table names to their respective metadata or structure.

    list_tables

    bool

    True

    Enables the functionality to list all tables in the database.

    describe_table

    bool

    True

    Enables the functionality to describe the schema of a specific table.

    run_sql_query

    bool

    True

    Enables the functionality to execute SQL queries directly.

    The consumer secret for Twitter API authentication

    access_token

    str

    None

    The access token for Twitter API authentication

    access_token_secret

    str

    None

    The access token secret for Twitter API authentication

    Introduction

    Agents are autonomous programs that achieve tasks using language models.

    Engineers use bitca to build agents with memory, knowledge, tools and reasoning.

    Example: Research Agent

    Let’s create a research agent that can search the web, read the top links and write a report for us. We “prompt” the agent using description and instructions.

    1

    Create Research Agent

    Create a file research_agent.py

    research_agent.py

    2

    Run the agent

    Install libraries

    Run the agent

    Capturing the Agent’s response in a variable

    While Agent.print_response() is useful for quick experiments, we typically want to capture the agent’s response in a variable to either pass to the frontend, another agent or use in our application. The Agent.run() function returns the response as a RunResponse object.

    By default stream=False, set stream=True to return a stream of RunResponse objects.

    RunResponse

    The Agent.run() function returns either a RunResponse object or an Iterator[RunResponse] when stream=True.

    RunResponse Attributes

    Attribute
    Type
    Default
    Description

    event

    str

    RunEvent.run_response.value

    Event type of the response.

    event_data

    Dict[str, Any]

    None

    Data associated with the event.

    messages

    List[Message]

    None

    A list of messages included in the response.

    metrics

    Dict[str, Any]

    None

    Usage metrics of the run.

    model

    Model

    OpenAIChat

    OpenAI model is used to run by default.

    run_id

    str

    None

    Run Id.

    agent_id

    str

    None

    Agent Id for the run.

    session_id

    str

    None

    Session Id for the run.

    tools

    List[Dict[str, Any]]

    None

    List of tools provided to the model.

    created_at

    int

    -

    Unix timestamp of the response creation.

    content

    Any

    None

    Content of the response.

    content_type

    str

    "str"

    Specifies the data type of the content.

    context

    List[MessageContext]

    None

    The context added to the response for RAG.

    from bitca.agent import Agent
    from bitca.model.openai import OpenAIChat
    from bitca.tools.duckduckgo import DuckDuckGo
    from bitca.tools.newspaper4k import Newspaper4k
    
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        tools=[DuckDuckGo(), Newspaper4k()],
        description="You are a senior NYT researcher writing an article on a topic.",
        instructions=[
            "For a given topic, search for the top 5 links.",
            "Then read each URL and extract the article text, if a URL isn't available, ignore it.",
            "Analyse and prepare an NYT worthy article based on the information.",
        ],
        markdown=True,
        show_tool_calls=True,
        add_datetime_to_instructions=True,
        # debug_mode=True,
    )
    agent.print_response("Simulation theory", stream=True)
    pip install bitca openai duckduckgo-search newspaper4k lxml_html_clean
    python research_agent.py
    from bitca.agent import Agent, RunResponse
    from bitca.utils.pprint import pprint_run_response
    
    agent = Agent(...)
    
    # Run agent and return the response as a variable
    response: RunResponse = agent.run("Simulation theory")
    # Print the response in markdown format
    pprint_run_response(response, markdown=True)
    from typing import Iterator
    
    # Run agent and return the response as a stream
    response_stream: Iterator[RunResponse] = agent.run("Simulation theory", stream=True)
    # Print the response stream in markdown format
    pprint_run_response(response_stream, markdown=True, show_time=True)