# Brainfork
**Brainfork** is an intelligent AI model router for Azure OpenAI that automatically selects the best model for your specific use case. It analyzes your conversations and routes them to the most appropriate AI model based on predefined use cases, keywords, and context requirements.
## Features
- 🎯 **Intelligent Routing**: Automatically selects the best AI model based on conversation context
- 🔧 **Flexible Configuration**: Support for multiple authentication methods (API key, Entra ID, Managed Identity)
- 📊 **Confidence Scoring**: Get confidence scores for routing decisions with detailed reasoning
- 🔄 **Multiple Use Cases**: Define custom use cases with keywords and context requirements
- 🚀 **Async Support**: Built with async/await for high-performance applications
- 📝 **Type Safety**: Full Pydantic model validation and type hints
## Installation
```bash
pip install brainfork
```
## Quick Start
Here's a complete example showing how to configure and use Brainfork:
```python
import asyncio
from brainfork import ModelRouter, ModelConfig, AuthConfig, UseCase
async def main():
# Configure your Azure OpenAI models
models = {
"gpt-4.1": ModelConfig(
endpoint="https://your-openai-endpoint.openai.azure.com/",
deployment_name="gpt-4.1",
api_version="2025-01-01-preview",
auth=AuthConfig(
client_id="your-client-id",
client_secret="your-client-secret",
tenant_id="your-tenant-id"
)
),
"gpt-5-mini": ModelConfig(
endpoint="https://your-openai-endpoint.openai.azure.com/",
deployment_name="gpt-5-mini",
api_version="2025-04-01-preview",
auth=AuthConfig(api_key="your-api-key")
),
"o3-mini": ModelConfig(
endpoint="https://your-openai-endpoint.openai.azure.com/",
deployment_name="o3-mini",
api_version="2025-01-01-preview",
auth=AuthConfig(api_key="your-api-key")
)
}
# Define use cases for intelligent routing
use_cases = [
UseCase(
name="math related questions",
description="when user is asking about math related questions or questions that require complex reasoning and analysis or coding",
model_name="o3-mini",
keywords=["math", "reasoning", "analysis", "problem", "solve", "calculate", "code", "programming", "function", "class", "debug"],
min_confidence=0.8
),
UseCase(
name="text summarization",
description="when user is asking for a summary of a text or document",
model_name="gpt-5-mini",
keywords=["summarize", "summary", "text", "document"],
min_confidence=0.8
),
UseCase(
name="new content generation",
description="when user is asking for new content generation like writing an article, story, or creative content",
model_name="gpt-4.1",
keywords=["create", "generate", "write", "article", "story", "content"],
min_confidence=0.75
)
]
# Initialize the router
router = ModelRouter(
models=models,
use_cases=use_cases,
default_model="gpt-5-mini",
routing_model="gpt-4.1-mini",
routing_temperature=0
)
# Example conversation
messages = [
{"role": "user", "content": "Write a Python function to implement binary search"}
]
# Route the conversation
result = await router.route_conversation(messages)
print(f"Selected Model: {result.model_name}")
print(f"Confidence: {result.confidence:.2f}")
print(f"Use Case: {result.use_case.name if result.use_case else 'None (default)'}")
print(f"Reasoning: {result.reasoning}")
# Get a configured client and make API call
configured_client = await router.get_configured_client(messages)
response = await configured_client.client.chat.completions.create(
model=configured_client.model_config.deployment_name,
messages=messages,
max_completion_tokens=1000
)
print(f"Response: {response.choices[0].message.content}")
if __name__ == "__main__":
asyncio.run(main())
```
## Routing Examples
Based on the conversation content, Brainfork intelligently routes to different models:
### 🧮 Mathematical/Coding Questions → o3-mini
```python
messages = [
{"role": "user", "content": "Solve this complex mathematical equation: x^3 + 2x^2 - 5x + 3 = 0"}
]
# Routes to o3-mini (specialized for reasoning and analysis)
```
### 📝 Text Summarization → gpt-5-mini
```python
messages = [
{"role": "user", "content": "Can you provide a summary of this news article: [long article text]"}
]
# Routes to gpt-5-mini (optimized for text processing)
```
### ✨ Creative Content → gpt-4.1
```python
messages = [
{"role": "user", "content": "Can you generate a creative story about friendship and adventure?"}
]
# Routes to gpt-4.1 (best for creative content generation)
```
### 🤔 General Questions → Default Model
```python
messages = [
{"role": "user", "content": "What's the reason we have different seasons on earth?"}
]
# Routes to gpt-5-mini (default model for general queries)
```
## Authentication Methods
Brainfork supports multiple authentication methods:
### API Key Authentication
```python
auth=AuthConfig(api_key="your-api-key")
```
### Entra ID Authentication
```python
auth=AuthConfig(
client_id="your-client-id",
client_secret="your-client-secret",
tenant_id="your-tenant-id"
)
```
### Managed Identity Authentication
```python
auth=AuthConfig(use_managed_identity=True)
```
## Configuration
### ModelConfig
Configure individual AI models with their endpoints and authentication:
```python
ModelConfig(
endpoint="https://your-endpoint.openai.azure.com/",
deployment_name="your-deployment",
api_version="2025-01-01-preview",
auth=AuthConfig(...),
max_tokens=4000, # Optional
temperature=0.7 # Optional
)
```
### UseCase
Define routing rules based on conversation context:
```python
UseCase(
name="use_case_name",
description="Detailed description of when to use this model",
model_name="target_model",
keywords=["keyword1", "keyword2"],
context_requirements=["requirement1"],
min_confidence=0.8
)
```
### ModelRouter
Initialize the router with your configuration:
```python
ModelRouter(
models=models_dict,
use_cases=use_cases_list,
default_model="fallback_model",
routing_model="model_for_routing_decisions",
routing_temperature=0
)
```
## API Reference
### Main Methods
#### `route_conversation(messages: List[Dict]) -> RoutingResult`
Routes a conversation to the most appropriate model.
#### `get_configured_client(messages: List[Dict]) -> ConfiguredClient`
Returns a configured Azure OpenAI client for the selected model.
#### `get_model_info() -> Dict`
Returns information about configured models and use cases.
### Response Objects
#### `RoutingResult`
- `model_name`: Selected model name
- `selected_model`: ModelConfig of selected model
- `use_case`: Matched UseCase (if any)
- `confidence`: Confidence score (0.0-1.0)
- `reasoning`: Explanation of routing decision
## Best Practices
1. **Define Clear Use Cases**: Create specific use cases with relevant keywords
2. **Set Appropriate Confidence Thresholds**: Balance between accuracy and fallback frequency
3. **Use Descriptive Model Names**: Make it easy to understand each model's purpose
4. **Monitor Routing Decisions**: Review confidence scores and reasoning for optimization
5. **Secure Your Credentials**: Use environment variables or Azure Key Vault for sensitive data
## Example Output
When running the example, you'll see output like:
```
🔄 Processing: Math Problem
User: Solve this complex mathematical equation: x^3 + 2x^2 - 5x + 3 = 0
✅ Selected Model: o3-mini
📊 Confidence: 0.95
🎯 Use Case: math related questions
💭 Reasoning: The user is asking to solve a complex mathematical equation, which requires mathematical reasoning and analysis. This matches the 'math related questions' use case with high confidence due to keywords like 'solve', 'mathematical', and 'equation'.
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/pfekrati/brainfork",
"name": "brainfork",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Pooyan Fekrati <p.fekrati@hotmail.com>",
"keywords": "azure, openai, ai, model, router, llm, gpt",
"author": "Pooyan",
"author_email": "Pooyan Fekrati <p.fekrati@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/0e/2b8b78aa1f974baed0e951a0578eb8f9c465d5046be3e9e798e2aeec81d9/brainfork-0.1.0.tar.gz",
"platform": null,
"description": "# Brainfork\r\n\r\n**Brainfork** is an intelligent AI model router for Azure OpenAI that automatically selects the best model for your specific use case. It analyzes your conversations and routes them to the most appropriate AI model based on predefined use cases, keywords, and context requirements.\r\n\r\n## Features\r\n\r\n- \ud83c\udfaf **Intelligent Routing**: Automatically selects the best AI model based on conversation context\r\n- \ud83d\udd27 **Flexible Configuration**: Support for multiple authentication methods (API key, Entra ID, Managed Identity)\r\n- \ud83d\udcca **Confidence Scoring**: Get confidence scores for routing decisions with detailed reasoning\r\n- \ud83d\udd04 **Multiple Use Cases**: Define custom use cases with keywords and context requirements\r\n- \ud83d\ude80 **Async Support**: Built with async/await for high-performance applications\r\n- \ud83d\udcdd **Type Safety**: Full Pydantic model validation and type hints\r\n\r\n## Installation\r\n\r\n```bash\r\npip install brainfork\r\n```\r\n\r\n## Quick Start\r\n\r\nHere's a complete example showing how to configure and use Brainfork:\r\n\r\n```python\r\nimport asyncio\r\nfrom brainfork import ModelRouter, ModelConfig, AuthConfig, UseCase\r\n\r\nasync def main():\r\n # Configure your Azure OpenAI models\r\n models = {\r\n \"gpt-4.1\": ModelConfig(\r\n endpoint=\"https://your-openai-endpoint.openai.azure.com/\",\r\n deployment_name=\"gpt-4.1\",\r\n api_version=\"2025-01-01-preview\",\r\n auth=AuthConfig(\r\n client_id=\"your-client-id\",\r\n client_secret=\"your-client-secret\",\r\n tenant_id=\"your-tenant-id\"\r\n )\r\n ),\r\n \"gpt-5-mini\": ModelConfig(\r\n endpoint=\"https://your-openai-endpoint.openai.azure.com/\",\r\n deployment_name=\"gpt-5-mini\",\r\n api_version=\"2025-04-01-preview\",\r\n auth=AuthConfig(api_key=\"your-api-key\") \r\n ),\r\n \"o3-mini\": ModelConfig(\r\n endpoint=\"https://your-openai-endpoint.openai.azure.com/\",\r\n deployment_name=\"o3-mini\",\r\n api_version=\"2025-01-01-preview\",\r\n auth=AuthConfig(api_key=\"your-api-key\")\r\n )\r\n }\r\n\r\n # Define use cases for intelligent routing\r\n use_cases = [\r\n UseCase(\r\n name=\"math related questions\",\r\n description=\"when user is asking about math related questions or questions that require complex reasoning and analysis or coding\",\r\n model_name=\"o3-mini\",\r\n keywords=[\"math\", \"reasoning\", \"analysis\", \"problem\", \"solve\", \"calculate\", \"code\", \"programming\", \"function\", \"class\", \"debug\"],\r\n min_confidence=0.8\r\n ),\r\n UseCase(\r\n name=\"text summarization\",\r\n description=\"when user is asking for a summary of a text or document\",\r\n model_name=\"gpt-5-mini\",\r\n keywords=[\"summarize\", \"summary\", \"text\", \"document\"],\r\n min_confidence=0.8\r\n ),\r\n UseCase(\r\n name=\"new content generation\",\r\n description=\"when user is asking for new content generation like writing an article, story, or creative content\",\r\n model_name=\"gpt-4.1\",\r\n keywords=[\"create\", \"generate\", \"write\", \"article\", \"story\", \"content\"],\r\n min_confidence=0.75\r\n )\r\n ]\r\n\r\n # Initialize the router\r\n router = ModelRouter(\r\n models=models,\r\n use_cases=use_cases,\r\n default_model=\"gpt-5-mini\",\r\n routing_model=\"gpt-4.1-mini\",\r\n routing_temperature=0\r\n )\r\n\r\n # Example conversation\r\n messages = [\r\n {\"role\": \"user\", \"content\": \"Write a Python function to implement binary search\"}\r\n ]\r\n\r\n # Route the conversation\r\n result = await router.route_conversation(messages)\r\n \r\n print(f\"Selected Model: {result.model_name}\")\r\n print(f\"Confidence: {result.confidence:.2f}\")\r\n print(f\"Use Case: {result.use_case.name if result.use_case else 'None (default)'}\")\r\n print(f\"Reasoning: {result.reasoning}\")\r\n\r\n # Get a configured client and make API call\r\n configured_client = await router.get_configured_client(messages)\r\n response = await configured_client.client.chat.completions.create(\r\n model=configured_client.model_config.deployment_name,\r\n messages=messages,\r\n max_completion_tokens=1000\r\n )\r\n \r\n print(f\"Response: {response.choices[0].message.content}\")\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(main())\r\n```\r\n\r\n## Routing Examples\r\n\r\nBased on the conversation content, Brainfork intelligently routes to different models:\r\n\r\n### \ud83e\uddee Mathematical/Coding Questions \u2192 o3-mini\r\n```python\r\nmessages = [\r\n {\"role\": \"user\", \"content\": \"Solve this complex mathematical equation: x^3 + 2x^2 - 5x + 3 = 0\"}\r\n]\r\n# Routes to o3-mini (specialized for reasoning and analysis)\r\n```\r\n\r\n### \ud83d\udcdd Text Summarization \u2192 gpt-5-mini\r\n```python\r\nmessages = [\r\n {\"role\": \"user\", \"content\": \"Can you provide a summary of this news article: [long article text]\"}\r\n]\r\n# Routes to gpt-5-mini (optimized for text processing)\r\n```\r\n\r\n### \u2728 Creative Content \u2192 gpt-4.1\r\n```python\r\nmessages = [\r\n {\"role\": \"user\", \"content\": \"Can you generate a creative story about friendship and adventure?\"}\r\n]\r\n# Routes to gpt-4.1 (best for creative content generation)\r\n```\r\n\r\n### \ud83e\udd14 General Questions \u2192 Default Model\r\n```python\r\nmessages = [\r\n {\"role\": \"user\", \"content\": \"What's the reason we have different seasons on earth?\"}\r\n]\r\n# Routes to gpt-5-mini (default model for general queries)\r\n```\r\n\r\n## Authentication Methods\r\n\r\nBrainfork supports multiple authentication methods:\r\n\r\n### API Key Authentication\r\n```python\r\nauth=AuthConfig(api_key=\"your-api-key\")\r\n```\r\n\r\n### Entra ID Authentication\r\n```python\r\nauth=AuthConfig(\r\n client_id=\"your-client-id\",\r\n client_secret=\"your-client-secret\",\r\n tenant_id=\"your-tenant-id\"\r\n)\r\n```\r\n\r\n### Managed Identity Authentication\r\n```python\r\nauth=AuthConfig(use_managed_identity=True)\r\n```\r\n\r\n## Configuration\r\n\r\n### ModelConfig\r\nConfigure individual AI models with their endpoints and authentication:\r\n\r\n```python\r\nModelConfig(\r\n endpoint=\"https://your-endpoint.openai.azure.com/\",\r\n deployment_name=\"your-deployment\",\r\n api_version=\"2025-01-01-preview\",\r\n auth=AuthConfig(...),\r\n max_tokens=4000, # Optional\r\n temperature=0.7 # Optional\r\n)\r\n```\r\n\r\n### UseCase\r\nDefine routing rules based on conversation context:\r\n\r\n```python\r\nUseCase(\r\n name=\"use_case_name\",\r\n description=\"Detailed description of when to use this model\",\r\n model_name=\"target_model\",\r\n keywords=[\"keyword1\", \"keyword2\"],\r\n context_requirements=[\"requirement1\"],\r\n min_confidence=0.8\r\n)\r\n```\r\n\r\n### ModelRouter\r\nInitialize the router with your configuration:\r\n\r\n```python\r\nModelRouter(\r\n models=models_dict,\r\n use_cases=use_cases_list,\r\n default_model=\"fallback_model\",\r\n routing_model=\"model_for_routing_decisions\",\r\n routing_temperature=0\r\n)\r\n```\r\n\r\n## API Reference\r\n\r\n### Main Methods\r\n\r\n#### `route_conversation(messages: List[Dict]) -> RoutingResult`\r\nRoutes a conversation to the most appropriate model.\r\n\r\n#### `get_configured_client(messages: List[Dict]) -> ConfiguredClient`\r\nReturns a configured Azure OpenAI client for the selected model.\r\n\r\n#### `get_model_info() -> Dict`\r\nReturns information about configured models and use cases.\r\n\r\n### Response Objects\r\n\r\n#### `RoutingResult`\r\n- `model_name`: Selected model name\r\n- `selected_model`: ModelConfig of selected model\r\n- `use_case`: Matched UseCase (if any)\r\n- `confidence`: Confidence score (0.0-1.0)\r\n- `reasoning`: Explanation of routing decision\r\n\r\n## Best Practices\r\n\r\n1. **Define Clear Use Cases**: Create specific use cases with relevant keywords\r\n2. **Set Appropriate Confidence Thresholds**: Balance between accuracy and fallback frequency\r\n3. **Use Descriptive Model Names**: Make it easy to understand each model's purpose\r\n4. **Monitor Routing Decisions**: Review confidence scores and reasoning for optimization\r\n5. **Secure Your Credentials**: Use environment variables or Azure Key Vault for sensitive data\r\n\r\n## Example Output\r\n\r\nWhen running the example, you'll see output like:\r\n\r\n```\r\n\ud83d\udd04 Processing: Math Problem\r\nUser: Solve this complex mathematical equation: x^3 + 2x^2 - 5x + 3 = 0\r\n\u2705 Selected Model: o3-mini\r\n\ud83d\udcca Confidence: 0.95\r\n\ud83c\udfaf Use Case: math related questions\r\n\ud83d\udcad Reasoning: The user is asking to solve a complex mathematical equation, which requires mathematical reasoning and analysis. This matches the 'math related questions' use case with high confidence due to keywords like 'solve', 'mathematical', and 'equation'.\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An intelligent AI model router for Azure OpenAI that automatically selects the best model for your specific use case",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/pfekrati/brainfork#readme",
"Homepage": "https://github.com/pfekrati/brainfork",
"Issues": "https://github.com/pfekrati/brainfork/issues",
"Repository": "https://github.com/pfekrati/brainfork"
},
"split_keywords": [
"azure",
" openai",
" ai",
" model",
" router",
" llm",
" gpt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5cb92e0b8b1e5e581b001c07b3a926d951be89320030af2bb74e2859bfb7a43b",
"md5": "256cb77eb46480c75388afd6de9a2e93",
"sha256": "b8bde82739698e1b3fd920aa8d171c4d8deb4a421edc813f79a43dffd96062e6"
},
"downloads": -1,
"filename": "brainfork-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "256cb77eb46480c75388afd6de9a2e93",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8552,
"upload_time": "2025-09-11T14:37:04",
"upload_time_iso_8601": "2025-09-11T14:37:04.613605Z",
"url": "https://files.pythonhosted.org/packages/5c/b9/2e0b8b1e5e581b001c07b3a926d951be89320030af2bb74e2859bfb7a43b/brainfork-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb0e2b8b78aa1f974baed0e951a0578eb8f9c465d5046be3e9e798e2aeec81d9",
"md5": "b866186c57f35ad28db32596a48bc479",
"sha256": "44858a42a81786fdf69473cccfc6906d2910144d0593c68093a519b9df7f7a27"
},
"downloads": -1,
"filename": "brainfork-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b866186c57f35ad28db32596a48bc479",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29197,
"upload_time": "2025-09-11T14:37:06",
"upload_time_iso_8601": "2025-09-11T14:37:06.106266Z",
"url": "https://files.pythonhosted.org/packages/bb/0e/2b8b78aa1f974baed0e951a0578eb8f9c465d5046be3e9e798e2aeec81d9/brainfork-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 14:37:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pfekrati",
"github_project": "brainfork",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "azure-ai-inference",
"specs": [
[
">=",
"1.0.0b4"
]
]
},
{
"name": "azure-identity",
"specs": [
[
">=",
"1.15.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.12.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.5.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.8.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.26.0"
]
]
},
{
"name": "structured-logprobs",
"specs": [
[
">=",
"0.1.5"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0.0"
]
]
}
],
"lcname": "brainfork"
}
JSON
