How agiresearch/cerebrum works
Project Type & Purpose
• Cerebrum is an open-source Python SDK + CLI for AIOS (the “AI Agent Operating System”).
• It provides libraries and command‐line tools to build, run, publish, and benchmark LLM-based AI Agents and Tools against the AIOS kernel and external LLM/providers.
File-Structure & Architectural Patterns
• Top-Level Modules:
– cerebrum/commands → CLI entrypoints (run-agent, list-*, download-agent/tool, upload-agent/tool, run-computer-use-agent)
– cerebrum/manager → orchestrator for Agents & Tools
– cerebrum/llm, cerebrum/memory, cerebrum/storage, cerebrum/tool → layered API modules
– cerebrum/tool/core + registry → built-in tool implementations & plugin registry
– cerebrum/community/adapter → adapter pattern for 3rd-party frameworks (Autogen, Interpreter, MetaGPT)
– cerebrum/interface → abstraction definitions for API layers
– cerebrum/example → sample agents/tools demonstrating folder structure & config
– run_cua.py + script.sh → specialized scripts for computer-use agent
– benchmarks/ → evaluation harness against multiple agents and scenarios
• Patterns: layered architecture (CLI → commands → manager → API layers → services), plugin/registry for tools, adapter for external agent frameworks.
a. Main Components
• CLI Layer
– Commands: run-agent, list-available-llms, download-agent, upload-tool, run-computer-use-agent
• Command Dispatcher
– cerebrum.commands.* modules
• Manager Layer
– cerebrum.manager.agent / .tool / .package
• API Layers
– LLM API: cerebrum.llm/apis.py, layer.py
– Memory API: cerebrum.memory/apis.py, layer.py
– Storage API: cerebrum.storage/apis.py, layer.py
– Tool API: cerebrum.tool/apis.py, base.py, layer.py
• Plugin Registry
– cerebrum.tool.core/registry.py → registers built-in tools
• Community Adapters
– cerebrum.community.adapter/* → wrap Autogen, Interpreter, MetaGPT
• Agent Execution Pipeline
– Agent entry.py + config.json + meta_requirements.txt
• Example & Benchmark Workflows
– cerebrum/example/* for demos
– benchmarks/experiment_core.py for evaluations
• External Services
– AIOS Kernel (RPC/HTTP)
– LLM Providers (OpenAI, Anthropic, HF, etc.)
– Remote AgentHub / ToolHub (HTTP)
– Third-party tool services (Google, Wikipedia, Wolfram, etc.)
b. Relationships & Data Flow
1. User invokes CLI → CLI parses args → calls corresponding cerebrum.commands module
2. Command module → Manager → loads Agent/Tool via config & registry
3. Manager coordinates:
– LLM API calls (to external LLM endpoints)
– Memory reads/writes (local/in-memory or remote)
– Storage operations (context persistence)
– Tool invocations (to core tool code or external service)
4. Community Adapters wrap this pipeline to integrate with other frameworks
5. Example agents/tools and Benchmarks plug into the same pipeline
c. Key Architectural Principles
– Layered Separation (CLI → Command → Manager → API → Services)
– Plugin/Registry Pattern for extensible Tools & Agents
– Adapter Pattern for external agent frameworks
– Config-Driven (JSON/YAML metadata drives discovery & wiring)
– Modular & Extensible: add new tools under cerebrum/tool/core, register them, write new commands if needed
d. Important Technologies & Frameworks
– Python 3.10/3.11
– Standard library + HTTP/gRPC for kernel communications
– JSON/YAML for configs
– External LLM clients (openai-python, anthropic-python, etc.)
– In-memory or file-based stores for memory/storage
– Shell scripts (script.sh, run_cua.py) for specialized workflows