# blueraai/universal-intelligence architecture

> Architecture diagram of the GitHub repository blueraai/universal-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blueraai/universal-intelligence
- Repository: https://github.com/blueraai/universal-intelligence

## Overview

Universal Intelligence is a cross-platform protocol and component library for composing models, tools, and agents. A user submits a task to an agent; the agent plans work with its model, dispatches selected tool or team-member methods, and uses the results to produce a response. The Python and TypeScript trees provide parallel implementations. Local Hugging Face inference, remote model providers, API/MCP tools, and playgrounds are distinct capabilities. The excerpts show agent dispatch and local inference mechanics; several provider and tool integrations are represented by paths and README capabilities, so their internal links are omitted where wiring is not shown.

Main entry points: [`universal_intelligence/community/agents/simple_agent/agent.py`](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/agents/simple_agent/agent.py) (Simple agent), [`playground/example.py`](https://github.com/blueraai/universal-intelligence/blob/main/playground/example.py) (Python playground), [`universal_intelligence/www/community/agents/simple_agent/agent.ts`](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/agents/simple_agent/agent.ts) (Simple agent), [`universal_intelligence/community/models/local/qwen2_5_7b_instruct/model.py`](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/models/local/qwen2_5_7b_instruct/model.py) (Local model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol contracts"]
  node_py_agent_contract["Agent contract<br/>[universal_agent.py]"]
  node_py_model_contract["Model contract<br/>[universal_model.py]"]
  node_py_tool_contract["Tool contract<br/>[universal_tool.py]"]
  node_py_types["Shared types<br/>[types.py]"]
  node_web_agent_contract["Agent contract<br/>[UniversalAgent.ts]"]
  node_web_model_contract["Model contract<br/>[UniversalModel.ts]"]
  node_web_tool_contract["Tool contract<br/>[UniversalTool.ts]"]
  node_web_types["Shared types<br/>[types.ts]"]
end

subgraph group_python["Python components"]
  node_py_agent["Simple agent<br/>[agent.py]"]
  node_py_hf["HF inference<br/>[interface.py]"]
  node_py_tools["Community tools"]
  node_playground["Python playground<br/>[example.py]"]
end

subgraph group_web["TypeScript components"]
  node_web_agent["Simple agent<br/>[agent.ts]"]
  node_web_hf["HF inference<br/>[interface.ts]"]
  node_web_remote["Remote registry<br/>[index.ts]"]
  node_web_api["API caller<br/>[tool.ts]"]
end

subgraph group_integrations["Model and tool integrations"]
  node_py_local["Local model<br/>[model.py]"]
  node_py_remote["Remote models"]
  node_api_tool["API caller<br/>[tool.py]"]
  node_mcp_tool["MCP client<br/>[tool.py]"]
  node_printer_tool["Simple printer<br/>[tool.py]"]
end

node_user(("Application user"))
node_remote_service(("Model provider"))

node_user -->|"submits task"| node_py_agent
node_py_agent -->|"uses model"| node_py_model_contract
node_py_agent -->|"dispatches methods"| node_py_tool_contract
node_py_agent -->|"defaults to"| node_py_local
node_py_local -.->|"uses inference"| node_py_hf
node_py_agent -->|"can invoke"| node_api_tool
node_py_agent -->|"can invoke"| node_printer_tool
node_py_agent -.->|"can invoke"| node_mcp_tool
node_py_remote -.->|"calls provider"| node_remote_service
node_user -.->|"submits task"| node_web_agent
node_web_agent -->|"uses model"| node_web_model_contract
node_web_agent -->|"dispatches methods"| node_web_tool_contract
node_web_agent -.->|"may use"| node_web_hf
node_web_remote -.->|"calls provider"| node_remote_service
node_playground -->|"runs example"| node_py_agent
node_playground -->|"runs example"| node_py_local
node_playground -->|"runs example"| node_api_tool
node_playground -->|"runs example"| node_printer_tool

click node_py_agent_contract "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/universal_agent.py"
click node_py_model_contract "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/universal_model.py"
click node_py_tool_contract "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/universal_tool.py"
click node_py_types "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/utils/types.py"
click node_py_agent "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/agents/simple_agent/agent.py"
click node_py_hf "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/models/__utils__/mixins/hf_text_to_text/interface.py"
click node_py_local "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/models/local/qwen2_5_7b_instruct/model.py"
click node_py_remote "https://github.com/blueraai/universal-intelligence/tree/main/universal_intelligence/community/models/remote"
click node_py_tools "https://github.com/blueraai/universal-intelligence/tree/main/universal_intelligence/community/tools"
click node_api_tool "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/tools/api_caller/tool.py"
click node_mcp_tool "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/tools/mcp_client/tool.py"
click node_printer_tool "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/tools/simple_printer/tool.py"
click node_web_agent_contract "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/UniversalAgent.ts"
click node_web_model_contract "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/UniversalModel.ts"
click node_web_tool_contract "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/UniversalTool.ts"
click node_web_types "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/types.ts"
click node_web_agent "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/agents/simple_agent/agent.ts"
click node_web_hf "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/models/__utils__/mixins/hf_text_to_text/interface.ts"
click node_web_remote "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/models/remote/index.ts"
click node_web_api "https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/tools/api_caller/tool.ts"
click node_playground "https://github.com/blueraai/universal-intelligence/blob/main/playground/example.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_agent_contract,node_py_model_contract,node_py_tool_contract,node_py_types,node_web_agent_contract,node_web_model_contract,node_web_tool_contract,node_web_types,node_user toneBlue
class node_py_agent,node_py_hf,node_py_tools,node_playground toneAmber
class node_web_agent,node_web_hf,node_web_remote,node_web_api toneMint
class node_py_local,node_py_remote,node_api_tool,node_mcp_tool,node_printer_tool toneRose
class node_remote_service toneIndigo
```

## Components

### Protocol contracts

- [Agent contract](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/universal_agent.py): `universal_intelligence/core/universal_agent.py`
- [Model contract](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/universal_model.py): `universal_intelligence/core/universal_model.py`
- [Tool contract](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/universal_tool.py): `universal_intelligence/core/universal_tool.py`
- [Shared types](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/core/utils/types.py): `universal_intelligence/core/utils/types.py`
- [Agent contract](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/UniversalAgent.ts): `universal_intelligence/www/core/UniversalAgent.ts`
- [Model contract](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/UniversalModel.ts): `universal_intelligence/www/core/UniversalModel.ts`
- [Tool contract](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/UniversalTool.ts): `universal_intelligence/www/core/UniversalTool.ts`
- [Shared types](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/core/types.ts): `universal_intelligence/www/core/types.ts`

### Python components

- [Simple agent](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/agents/simple_agent/agent.py): `universal_intelligence/community/agents/simple_agent/agent.py`
- [HF inference](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/models/__utils__/mixins/hf_text_to_text/interface.py): `universal_intelligence/community/models/__utils__/mixins/hf_text_to_text/interface.py`
- [Community tools](https://github.com/blueraai/universal-intelligence/tree/main/universal_intelligence/community/tools): `universal_intelligence/community/tools`
- [Python playground](https://github.com/blueraai/universal-intelligence/blob/main/playground/example.py): `playground/example.py`

### TypeScript components

- [Simple agent](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/agents/simple_agent/agent.ts): `universal_intelligence/www/community/agents/simple_agent/agent.ts`
- [HF inference](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/models/__utils__/mixins/hf_text_to_text/interface.ts): `universal_intelligence/www/community/models/__utils__/mixins/hf_text_to_text/interface.ts`
- [Remote registry](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/models/remote/index.ts): `universal_intelligence/www/community/models/remote/index.ts`
- [API caller](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/www/community/tools/api_caller/tool.ts): `universal_intelligence/www/community/tools/api_caller/tool.ts`

### Model and tool integrations

- [Local model](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/models/local/qwen2_5_7b_instruct/model.py): `universal_intelligence/community/models/local/qwen2_5_7b_instruct/model.py`
- [Remote models](https://github.com/blueraai/universal-intelligence/tree/main/universal_intelligence/community/models/remote): `universal_intelligence/community/models/remote`
- [API caller](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/tools/api_caller/tool.py): `universal_intelligence/community/tools/api_caller/tool.py`
- [MCP client](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/tools/mcp_client/tool.py): `universal_intelligence/community/tools/mcp_client/tool.py`
- [Simple printer](https://github.com/blueraai/universal-intelligence/blob/main/universal_intelligence/community/tools/simple_printer/tool.py): `universal_intelligence/community/tools/simple_printer/tool.py`

### Other components

- **Application user**
- **Model provider**

## Connections

- Application user → Simple agent: submits task
- Simple agent → Model contract: uses model (evidence: `universal_intelligence/community/agents/simple_agent/agent.py`)
- Simple agent → Tool contract: dispatches methods (evidence: `universal_intelligence/community/agents/simple_agent/agent.py`)
- Simple agent → Local model: defaults to (evidence: `universal_intelligence/community/agents/simple_agent/agent.py`)
- Local model → HF inference: uses inference
- Simple agent → API caller: can invoke
- Simple agent → Simple printer: can invoke
- Simple agent → MCP client: can invoke
- Remote models → Model provider: calls provider
- Application user → Simple agent: submits task
- Simple agent → Model contract: uses model (evidence: `universal_intelligence/www/community/agents/simple_agent/agent.ts`)
- Simple agent → Tool contract: dispatches methods (evidence: `universal_intelligence/www/community/agents/simple_agent/agent.ts`)
- Simple agent → HF inference: may use
- Remote registry → Model provider: calls provider
- Python playground → Simple agent: runs example (evidence: `playground/example.py`)
- Python playground → Local model: runs example (evidence: `playground/example.py`)
- Python playground → API caller: runs example (evidence: `playground/example.py`)
- Python playground → Simple printer: runs example (evidence: `playground/example.py`)