# OpenBrain
[](https://www.gnu.org/licenses/agpl-3.0)[](https://github.com/astral-sh/ruff)
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
[](https://conventionalcommits.org)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/features/actions "Go to GitHub Actions homepage")
[](https://github.com/semantic-release/semantic-release)
## Links
- [AI Agent Tuner](https://tuner.openbra.in):
- 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 Deployed Agent Page](https://www.openbra.in):
- An example page that's using the agent from the public demo API.
- This page uses an identity registered with [OpenBrain Portal](https://portal.openbra.in).
- This page is using the [OpenBrain API](https://api.openbra.in) API to interact with LLMs.
- This page is configured to use the client id `openbrain` and the profile called `promoter`, but it can, of course, use any stored agent configuration. The site is sending messages like this
```json
{
"client_id": "openbrain",
"profileName": "promoter",
"message": "Hi, this is a message from the user talking through the website. I want to schedule an appointment or something."
}
- [OpenBrain Portal](https://portal.openbra.in):
- Sign up for OpenBra.in as a service. Get an API key and start using 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 [https://portal.openbra.in](https://portal.openbra.in).
2. Log in to the portal and subscribe to the Openbrain chat endpoint.
3. Navigate to your dashboard in the portal to find and use your API keys.
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.
- **Interactive Agent Tuner**: Integrates with deployable web interface `ob-tuner`.
- **Command-Line Interface**: Use `ob` for quick completions and `ob-chat` for an interactive session.
- **Flexible Configuration**: Customizable, persistent agent configurations.
- **Event-Driven Architecture**: Tools that operate on the real world send events to the event bus.
## AI Agent Tools
### Context
OpenBrain agents can use tools, and those 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.
```json
{
"client_id": "me@email.com", // OpenBrain parameter
"reset": true, // OpenBrain parameter
"message": "Do a barrel roll", // OpenBrain parameter
"email": "hotlead@public.com", // context
"firstName": "John", // context
"lastName": "Doe", // context
"phone": "555-555-5555" // context
}
```
### Tools
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.
- **simple_calculator**: Perform a simple calculation.
#### 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.
## Architecture Overview
### Data Model
```mermaid
classDiagram
class ChatMessage {
+ str: sessionId
+ str: clientId
+ str: message
+ AgentConfig: agentConfigOverrides
+ str: agentConfig
+ bool: reset
+ str: context...
}
class AgentConfig {
+ str: profileName
+ str: clientId
+ str: iceBreaker
+ Decimal: temperature
+ ...
+ save()
+ refresh()
+ get()
}
class ChatSession {
+ str: sessionId
+ str: clientId
+ byte: agentMemory
+ AgentConfig: agentConfig
+ save()
+ get()
}
ChatSession "1" *-- "1" AgentConfig: contains
langchain_ChatMemory "1" *-- "1" ChatMessage: n messages ingested by agent, stored in memory
%% 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.
```mermaid
sequenceDiagram
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
end
box purple Tool
participant Tool
end
box gray EventBus
participant EventBus
end
box red Provider
participant OpenAI
end
```
```mermaid
sequenceDiagram
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
Lambda ->> SQS: <DETAILS NEEDED TO RETRY>
ExternalSite ->> Lambda: ...
Lambda -> EventBus: <POTENTIAL NEW EVENT>
box maroon DeadLetterQueue
participant SQS
end
box blue Databases
participant ObjectTable
participant AgentConfigTable
participant ChatHistoryTable
end
box gray EventBus
participant EventBus
end
box brown EventTargets
participant Lambda
end
box green Internet
participant ExternalSite
end
```
### Example X-Ray diagram from live test
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
- **Open Source**: AGPLv3
- **Commercial**: See [COMMERCIAL_LICENSE](COMMERCIAL_LICENSE) and contact us for inquiries.
Raw data
{
"_id": null,
"home_page": "https://github.com/svange/openbrain",
"name": "openbrain",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Samuel Vange",
"author_email": "7166607+svange@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/47/a5/b498bb906dc6d4c8213d2efdbac96c2927e4d9770f4ce65d3e4bb90a63cd/openbrain-5.7.0.tar.gz",
"platform": null,
"description": "# OpenBrain\n\n\n\n\n\n[](https://www.gnu.org/licenses/agpl-3.0)[](https://github.com/astral-sh/ruff)\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n[](https://conventionalcommits.org)\n[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/features/actions \"Go to GitHub Actions homepage\")\n[](https://github.com/semantic-release/semantic-release)\n\n## Links\n\n- [AI Agent Tuner](https://tuner.openbra.in):\n\n - A Gradio interface to create, test, save, and load sets of agent configurations.\n - Agent configurations allows your API calls to start sessions with a specific agent configuration (i.e. lead-bot, cold-caller, x-bot, etc.).\n\n\n\n- [Demo Deployed Agent Page](https://www.openbra.in):\n\n - An example page that's using the agent from the public demo API.\n - This page uses an identity registered with [OpenBrain Portal](https://portal.openbra.in).\n - This page is using the [OpenBrain API](https://api.openbra.in) API to interact with LLMs.\n - This page is configured to use the client id `openbrain` and the profile called `promoter`, but it can, of course, use any stored agent configuration. The site is sending messages like this\n ```json\n {\n \"client_id\": \"openbrain\",\n \"profileName\": \"promoter\",\n \"message\": \"Hi, this is a message from the user talking through the website. I want to schedule an appointment or something.\"\n }\n\n\n- [OpenBrain Portal](https://portal.openbra.in):\n\n - Sign up for OpenBra.in as a service. Get an API key and start using the API.\n - 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).\n\n\n## Openbrain as a Service\n\nTo test Openbrain as a service, do the following:\n\n1. Register at [https://portal.openbra.in](https://portal.openbra.in).\n2. Log in to the portal and subscribe to the Openbrain chat endpoint.\n3. Navigate to your dashboard in the portal to find and use your API keys.\n\nNOTE: 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.\n\n- **Interactive Agent Tuner**: Integrates with deployable web interface `ob-tuner`.\n- **Command-Line Interface**: Use `ob` for quick completions and `ob-chat` for an interactive session.\n- **Flexible Configuration**: Customizable, persistent agent configurations.\n- **Event-Driven Architecture**: Tools that operate on the real world send events to the event bus.\n\n## AI Agent Tools\n\n### Context\n\nOpenBrain agents can use tools, and those 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.\n\n```json\n{\n \"client_id\": \"me@email.com\", // OpenBrain parameter\n \"reset\": true, // OpenBrain parameter\n \"message\": \"Do a barrel roll\", // OpenBrain parameter\n \"email\": \"hotlead@public.com\", // context\n \"firstName\": \"John\", // context\n \"lastName\": \"Doe\", // context\n \"phone\": \"555-555-5555\" // context\n}\n```\n\n### Tools\n\nOpenBrain 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.\n\nTools 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.\n\n#### Generic Tools\n\nThese 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.\n\n- **get_current_time**: Get the current time.\n- **simple_calculator**: Perform a simple calculation.\n\n#### 3rd party services\n\n- **lls_scrub_phone_number**: Get DNC information for a phone number.\n - api_key (optional): The API key for the LLS service. If not provided, the default key will be used from AWS Secrets Manager.\n\n#### CRM support for Lead Momentum\n\n- **leadmo_update_contact**: Update a contact in Lead Momentum.\n- **leadmo_stop_conversation**: Stop a conversation in Lead Momentum.\n- **leadmo_create_contact**: Create a contact in Lead Momentum.\n- **leadmo_delete_contact**: Delete a contact in Lead Momentum.\n- **leadmo_get_contact_details_from_context**: Get contact details from this request's context to be made available to the AI.\n- **leadmo_get_simple_calendar-appointment_slots**: Get available appointment slots from Lead Momentum.\n- **leadmo_create_appointment**: Create an appointment in Lead Momentum.\n\n## Architecture Overview\n\n### Data Model\n\n```mermaid\nclassDiagram\n class ChatMessage {\n + str: sessionId\n + str: clientId\n + str: message\n + AgentConfig: agentConfigOverrides\n + str: agentConfig\n + bool: reset\n + str: context...\n }\n\n class AgentConfig {\n + str: profileName\n + str: clientId\n + str: iceBreaker\n + Decimal: temperature\n + ...\n + save()\n + refresh()\n + get()\n }\n\n class ChatSession {\n + str: sessionId\n + str: clientId\n + byte: agentMemory\n + AgentConfig: agentConfig\n + save()\n + get()\n }\n\n\n ChatSession \"1\" *-- \"1\" AgentConfig: contains\n langchain_ChatMemory \"1\" *-- \"1\" ChatMessage: n messages ingested by agent, stored in memory\n%% ChatSession \"1\" *-- \"*\" ChatMessage: contains\n ChatSession \"1\" *-- \"1\" langchain_ChatMemory: from langchain, serialized\n```\n\n# Data Flow diagram\n\nOpenBrain 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.\n\n1. The user interaction with the agent and the agent interaction with an event bus.\n2. The event bus and the targets that are triggered by the events.\n\n```mermaid\nsequenceDiagram\n title Agent Data Flow\n participant User\n create participant GPT Agent\n participant AgentConfigTable\n participant OpenAI\n participant Tool\n participant EventBus\n\n User ->> GPT Agent: (AgentConfig, AgentMemory, Lead, Email, InitialContext), ChatMessage\n GPT Agent -->> AgentConfigTable: profileName, clientId (on reset)\n AgentConfigTable -->> GPT Agent: AgentConfig (on reset)\n GPT Agent ->> GPT Agent: InitialContext, Email, Lead (on reset) \n GPT Agent -->> OpenAI: ChatMessage (on chat)\n OpenAI -->> GPT Agent: ChatMessage (on chat)\n GPT Agent -->> Tool: Tool(Object, clientId) (on chat)\n Tool -->> EventBus: (Object, clientId, session_id, object_id)\n Tool -->> GPT Agent: ChatMessage (on chat)\n destroy GPT Agent\n GPT Agent ->> User: ChatMessage, (AgentConfig, AgentMemory), Object\n\n box blue Databases\n participant AgentConfigTable\n end\n box purple Tool\n participant Tool\n end\n\n box gray EventBus\n participant EventBus\n end\n\n box red Provider\n participant OpenAI\n end\n```\n\n```mermaid\nsequenceDiagram\n title Example tool event data flow\n participant SQS\n participant EventBus\n participant Lambda\n participant ObjectTable\n participant AgentConfigTable\n participant ChatHistoryTable\n participant ExternalSite\n\n EventBus ->> Lambda: (Object, clientId, sessionId, objectId)\n Lambda -->> ObjectTable: (clientId, objectId)\n ObjectTable -->> Lambda: Object\n\n Lambda -->> AgentConfigTable: (profileName, clientId)\n ChatHistoryTable -->> Lambda: AgentConfig\n\n Lambda --> ChatHistoryTable: (clientId, sessionId)\n ChatHistoryTable -->> Lambda: (AgentMemory, AgentConfig)\n\n Lambda ->> ExternalSite: ...\n ExternalSite --x Lambda: ERROR\n Lambda ->> SQS: <DETAILS NEEDED TO RETRY>\n ExternalSite ->> Lambda: ...\n\n Lambda -> EventBus: <POTENTIAL NEW EVENT>\n\n box maroon DeadLetterQueue\n participant SQS\n end\n\n box blue Databases\n participant ObjectTable\n participant AgentConfigTable\n participant ChatHistoryTable\n end\n\n box gray EventBus\n participant EventBus\n end\n\n box brown EventTargets\n participant Lambda\n end\n\n box green Internet\n participant ExternalSite\n end\n\n\n```\n\n### Example X-Ray diagram from live test\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n- **Open Source**: AGPLv3\n- **Commercial**: See [COMMERCIAL_LICENSE](COMMERCIAL_LICENSE) and contact us for inquiries.\n",
"bugtrack_url": null,
"license": "AGPL-3.0-only",
"summary": "A package to interact with generative AI and build specialized generative AI workflows.",
"version": "5.7.0",
"project_urls": {
"Homepage": "https://github.com/svange/openbrain"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db925a4ed277e84f2a48acd130c3f027a67d701647619b4e351ec9ed07973aeb",
"md5": "b8860699ad30a260c12a83f43554db81",
"sha256": "47ff645df5e565de2205af247be21ae6a26081d908e36b4d21d3e061ac76278c"
},
"downloads": -1,
"filename": "openbrain-5.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8860699ad30a260c12a83f43554db81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 62353,
"upload_time": "2024-09-11T19:02:45",
"upload_time_iso_8601": "2024-09-11T19:02:45.452940Z",
"url": "https://files.pythonhosted.org/packages/db/92/5a4ed277e84f2a48acd130c3f027a67d701647619b4e351ec9ed07973aeb/openbrain-5.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "47a5b498bb906dc6d4c8213d2efdbac96c2927e4d9770f4ce65d3e4bb90a63cd",
"md5": "5cebbb3c80f6ec899d17964c5d18384f",
"sha256": "722911f05112574e2ef6a7f4e04d67d19007c4d941432831867b09b726ba0094"
},
"downloads": -1,
"filename": "openbrain-5.7.0.tar.gz",
"has_sig": false,
"md5_digest": "5cebbb3c80f6ec899d17964c5d18384f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 46198,
"upload_time": "2024-09-11T19:02:46",
"upload_time_iso_8601": "2024-09-11T19:02:46.948213Z",
"url": "https://files.pythonhosted.org/packages/47/a5/b498bb906dc6d4c8213d2efdbac96c2927e4d9770f4ce65d3e4bb90a63cd/openbrain-5.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 19:02:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "svange",
"github_project": "openbrain",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openbrain"
}
JSON
