Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



A package to interact with generative AI and build specialized generative AI workflows. This project is dual-licensed under AGPL-3.0 and a separate commercial license.




ci status ci status

PyPI - Version License: AGPL v3Ruff Code style: black Conventional Commits pre-commit Made with GH Actions semantic-release


  • Agent Tuner:

    • A Gradio interface to create, test, save, and load sets of agent configurations.
    • Agent configurations allows your API calls to start sessions with a specific agent configuration (i.e. lead-bot, cold-caller, x-bot, etc.).
  • Demo Agent Page:

    • An example page that's using the agent from the public demo API.
    • This page uses an identity registered with OpenBrain Portal.
    • This page is using the OpenBrain API API to interact with LLMs.
    • This page is configured to use the profile called "default", but it can, of course, use any stored agent configuration.
  • OpenBrain Portal:

    • Sign up for as a service. Get an API key and start using the API. Swagger UI available once subscribed to the API.
    • This method does not require you to use the library or to deploy any infrastructure. Just grab an API key, and you can simply start with axios or the requests library (or whatever your language provides for making HTTP requests).

Openbrain as a Service

To test Openbrain as a service, do the following:

  1. Register at
  2. Log in to the portal and subscribe to the Openbrain service.
  3. Navigate to your dashboard in the portal and use your API keys to interact with the API.
  4. A swagger UI and SDKs are available for subscribers.

NOTE: There is currently no fee for using the service, but it's using my personal AWS and OpenAI accounts, so I'll pull the plug immediately if it becomes expensive.


  • Infrastructure as Code: Deploy to AWS using CodePipeline and SAM.
  • Interactive Agent Tuner: A GUI to modify and test agent configurations available as Python package ob-tuner.
  • Command-Line Interface: Use ob for quick completions and ob-chat for an interactive session.
  • Flexible Configuration: Customizable agents through DynamoDB backed ORM.
  • Event-Driven Architecture: Extensible through cloud-based event handling.

AI Agent Tools


OpenBrain tools get input rom 2 sources: the agent's input values, and input values from "context". The "context" is any undocumented key/value pair. This is done in order to allow the agent to call tools that require sensitive information that we don't want the AI to have access to.


OpenBrain tools are categorized into 2 types: information retrieval tools, and action tools. Information retrieval tools are tools that get information from a 3rd party service or library and make that information available to the AI. Action tools, on the other hand, are tools that perform an action, such as updating a CRM, sending an email, etc. These "action tools" all operate in the same way, by taking the agent's input and context as input, and returning a creating an event on the the event mesh.

Tools need adaptors, so even action tools need OpenBrain support in order to make the AI aware of what input parameters these action tools require. Information retrieval tools, on the other hand, can not be implemented trivially using an event mesh, as the AI needs to be aware of the information that was retrieved immediately, so these tools are implemented directly in openBrain.

Generic Tools

These tools are available to all agents. Each tool is listed by name with a brief description of its functionality, and lists the required context keys.

  • get_current_time: Get the current time.
    • N/A
3rd party services
  • lls_scrub_phone_number: Get DNC information for a phone number.
    • api_key (optional): The API key for the LLS service. If not provided, the default key will be used from AWS Secrets Manager.
CRM support for Lead Momentum
  • leadmo_update_contact: Update a contact in Lead Momentum.
  • leadmo_stop_conversation: Stop a conversation in Lead Momentum.
  • leadmo_create_contact: Create a contact in Lead Momentum.
  • leadmo_delete_contact: Delete a contact in Lead Momentum.
  • leadmo_get_contact_details_from_context: Get contact details from this request's context to be made available to the AI.
  • leadmo_get_simple_calendar-appointment_slots: Get available appointment slots from Lead Momentum.
  • leadmo_create_appointment: Create an appointment in Lead Momentum.

Quick Start

# TLDR: demo functionality
pip install openbrain[gradio]

To print an example .env file, use ob-env.



Gradio is included as an extra dependency. This keeps the base installation small enough to fit in a lambda layer. If you intend to experiment with the ob-tuner interface locally, add the [gradio] extra to your pip install command.

pip install openbrain[gradio]

Setup .env file

cp .env.example .env  # Edit this file with your own values

Deploy Supporting Infrastructure

The AgentConfigs you create in ob-tuner can be saved to your DynamoDB tables in AWS, allowing you to reference them in any AWS workflow using the boto3 library.

If you intend to use this project in your API, an AWS SAM template is provided to get you started. You can deploy the template using the following command. You will need to have the AWS CLI installed and configured with your credentials.

:warning: This will deploy resources to your AWS account. :warning: You will be charged for these resources. See AWS Pricing for more information.

python -I

Using OpenBrain

OpenBrain Gradio Tuner

To facilitate tuning agent parameters and experimenting with prompts, OpenBrain provides a GUI interface using Gradio. You can use the in-memory object model to store your agent configurations locally. This is controllable by setting GRADIO_LOCAL=True, ORM_LOCAL=True, UTIL_LOCAL=True in your .env file.


$ ob-tuner
Running on local URL:

To create a public link, set `share=True` in `launch()`.
Tip: You can show or hide the button for flagging with the `allow_flagging=` kwarg; for example: gr.Interface(..., allow_flagging=False)

Command Line Completions

(doesn't work quite like this yet, but that's the idea, currently noisy)

$ ob --profile_name=linux 'change the file permissions of all files that start with a "w" in this directory (recursively) to 042'

find . -type f -name 'w*' -exec chmod 042 {} +

Command Line Interactive Session

(doesn't work quite like this yet, but that's the idea)

$ ob-chat
---------- Begin Chat Session ----------
> OpenBrain: What… is your name?
User: It is Arthur – King of the Britons.
> OpenBrain: What… is your quest?
User: To seek the Holy Grail.
> OpenBrain: What… is the air-speed velocity of an unladen swallow?
User: What do you mean? An African or a European swallow?
> OpenBrain: I don’t know that. Aaaaaaaaagh!

Architecture Overview

Data Model

    class ChatMessage {
        User provided*
        + str: sessionId
        + str: clientId
        + str: message
        + str: email
        + AgentConfig: agentConfigOverrides
        + str: agentConfig
        + bool: reset

    class AgentConfig {
        + str: profileName
        + str: clientId
        + str: iceBreaker
        + Decimal: temperature
        + ...
        + save()
        + refresh()
        + load()
        + delete()
        + get_all()

    class ChatSession {
        + str: sessionId
        + str: clientId
        + byte: agentMemory
        + AgentConfig: agentConfig
        + Lead: lead
        + save()
        + load()

    class Lead {
        + str: sessionId
        + str: clientId
        + str: fullName
        + str: firstName
        + str: middleName
        + str: lastName
        + List[str]: medications
        + str: email
        + ...
        + save()
        + refresh()
        + delete()
        + load()
        + get_all()

    ChatSession "1" *-- "1" Lead: contains
    ChatSession "1" *-- "1" AgentConfig: contains
%%    ChatMessage "1" *-- "1" AgentConfig: contains
%%    ChatSession "1" *-- "*" ChatMessage: contains
    ChatSession "1" *-- "1" langchain_ChatMemory: from langchain, serialized

Data Flow diagram

OpenBrain uses an event driven architecture. The agent sends events to event bus and then the developer can simply write rules and targets for the incoming events once the targets are ready. The following diagram shows the data flow in two parts.

  1. The user interaction with the agent and the agent interaction with an event bus.
  2. The event bus and the targets that are triggered by the events.
    title Agent Data Flow
    participant User
    create participant GPT Agent
    participant AgentConfigTable
    participant OpenAI
    participant Tool
    participant EventBus

    User ->> GPT Agent: (AgentConfig, AgentMemory, Lead, Email, InitialContext), ChatMessage
        GPT Agent -->> AgentConfigTable: profileName, clientId (on reset)
        AgentConfigTable -->> GPT Agent: AgentConfig (on reset)
        GPT Agent ->> GPT Agent: InitialContext, Email, Lead (on reset)  
        GPT Agent -->> OpenAI: ChatMessage (on chat)
        OpenAI -->> GPT Agent: ChatMessage (on chat)
        GPT Agent -->> Tool: Tool(Object, clientId) (on chat)
        Tool -->> EventBus: (Object, clientId, session_id, object_id)
        Tool -->> GPT Agent: ChatMessage (on chat)
    destroy GPT Agent
    GPT Agent ->> User: ChatMessage, (AgentConfig, AgentMemory), Object

  box blue Databases
      participant AgentConfigTable
  box purple Tool
      participant Tool

  box gray EventBus
      participant EventBus

  box red Provider
      participant OpenAI
    title Example tool event data flow
    participant SQS
    participant EventBus
    participant Lambda
    participant ObjectTable
    participant AgentConfigTable
    participant ChatHistoryTable
    participant ExternalSite

    EventBus ->> Lambda: (Object, clientId, sessionId, objectId)
    Lambda -->> ObjectTable: (clientId, objectId)
    ObjectTable -->> Lambda: Object

    Lambda -->> AgentConfigTable: (profileName, clientId)
    ChatHistoryTable -->> Lambda: AgentConfig

    Lambda --> ChatHistoryTable: (clientId, sessionId)
    ChatHistoryTable -->> Lambda: (AgentMemory, AgentConfig)

    Lambda ->> ExternalSite: ...
    ExternalSite --x Lambda: ERROR
    ExternalSite ->> Lambda: ...

    Lambda -> EventBus: <POTENTIAL NEW EVENT>

    box maroon DeadLetterQueue
        participant SQS

    box blue Databases
        participant ObjectTable
        participant AgentConfigTable
        participant ChatHistoryTable

    box gray EventBus
        participant EventBus

    box brown EventTargets
        participant Lambda

    box green Internet
        participant ExternalSite


See for guidelines.



Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc