mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Add Optimal Brain architecture and workflow documentation
- docs/rag/architecture/optimal-brain.md: Complete architecture overview - docs/rag/workflows/proactive-knowledge.md: Task context injection workflow - docs/rag/workflows/cross-agent-learning.md: Learning network workflow - docs/rag/workflows/rule-enforcement.md: Standards validation workflow
This commit is contained in:
Claude
@@ -0,0 +1,261 @@
|
||||
# Optimal Brain Architecture
|
||||
|
||||
The Optimal Brain is RoboCo's organizational intelligence layer - a knowledge system that enables agents to learn from each other, enforce standards, and make consistent decisions.
|
||||
|
||||
## Overview
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------------------+
|
||||
| OPTIMAL BRAIN |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
||||
| | Mentor | | Error | | Decision | | Standards | |
|
||||
| | System | | Patterns | | Memory | | Enforcer | |
|
||||
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | Learning | | Proactive | | Code | |
|
||||
| | Network | | Context | | Review | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | | | | |
|
||||
| +---------------+---------------+---------------+ |
|
||||
| | |
|
||||
| +------------------------+ |
|
||||
| | Piragi + pgvector | |
|
||||
| | (PostgreSQL) | |
|
||||
| +------------------------+ |
|
||||
+-----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Index Types
|
||||
|
||||
| Index | Content | Auto-Updated |
|
||||
|-------|---------|--------------|
|
||||
| `code` | Source files | On commit |
|
||||
| `docs` | Documentation | On write |
|
||||
| `decisions` | Architectural choices | Manual |
|
||||
| `errors` | Error patterns + solutions | Manual |
|
||||
| `standards` | Coding/security/workflow rules | On boot |
|
||||
| `learnings` | Agent insights | Manual |
|
||||
| `reviews` | Code review patterns | On review |
|
||||
| `conversations` | Channel discussions | On message |
|
||||
| `journals` | Agent reflections | On entry |
|
||||
|
||||
## Components
|
||||
|
||||
### 1. Mentor System
|
||||
|
||||
Conversational RAG for agent questions. Maintains context across follow-ups.
|
||||
|
||||
**Tool:** `roboco_ask_mentor`
|
||||
|
||||
```python
|
||||
# First question
|
||||
response = roboco_ask_mentor(question="How do I handle auth?")
|
||||
|
||||
# Follow-up (uses conversation context)
|
||||
roboco_ask_mentor(
|
||||
question="What about refresh tokens?",
|
||||
conversation_id=response["conversation_id"]
|
||||
)
|
||||
```
|
||||
|
||||
**Searches:** standards, decisions, learnings, code, errors
|
||||
|
||||
### 2. Error Pattern Database
|
||||
|
||||
Collective error memory. When one agent solves an error, all agents benefit.
|
||||
|
||||
**Tools:** `roboco_search_error`, `roboco_record_error_solution`
|
||||
|
||||
```python
|
||||
# Before debugging
|
||||
roboco_search_error(error_message="Redis timeout", context="startup")
|
||||
|
||||
# After fixing
|
||||
roboco_record_error_solution(
|
||||
error_message="Redis timeout",
|
||||
solution="Added retry with exponential backoff",
|
||||
worked=True
|
||||
)
|
||||
```
|
||||
|
||||
### 3. Decision Memory
|
||||
|
||||
Prevents inconsistent architectural choices. Check before deciding.
|
||||
|
||||
**Tools:** `roboco_check_decision`, `roboco_record_decision`
|
||||
|
||||
```python
|
||||
# Before deciding
|
||||
roboco_check_decision(topic="session storage")
|
||||
|
||||
# After deciding
|
||||
roboco_record_decision(params={
|
||||
"topic": "Session storage",
|
||||
"decision": "Use Redis",
|
||||
"rationale": "Sub-ms reads, existing infra"
|
||||
})
|
||||
```
|
||||
|
||||
### 4. Standards Enforcer
|
||||
|
||||
Pre-action validation against organizational rules.
|
||||
|
||||
**Tools:** `roboco_get_standards`, `roboco_validate_action`, `roboco_review_code`
|
||||
|
||||
```python
|
||||
# Before writing code
|
||||
roboco_get_standards(domain="coding", language="python")
|
||||
|
||||
# Validate action
|
||||
roboco_validate_action(
|
||||
action_type="create_endpoint",
|
||||
context="Adding /users POST endpoint"
|
||||
)
|
||||
|
||||
# Review code
|
||||
roboco_review_code(code="...", file_path="api/users.py")
|
||||
```
|
||||
|
||||
### 5. Learning Network
|
||||
|
||||
Cross-agent knowledge sharing. Learnings propagate organization-wide.
|
||||
|
||||
**Tools:** `roboco_record_learning`, `roboco_search_learnings`
|
||||
|
||||
```python
|
||||
# Record insight
|
||||
roboco_record_learning(
|
||||
content="Use transactions for multi-table updates",
|
||||
category="pattern",
|
||||
shareable=True
|
||||
)
|
||||
|
||||
# Search learnings
|
||||
roboco_search_learnings(query="database transactions")
|
||||
```
|
||||
|
||||
### 6. Proactive Context
|
||||
|
||||
Auto-injected knowledge when agents claim tasks.
|
||||
|
||||
**Tool:** `roboco_get_proactive_context`
|
||||
|
||||
Returns:
|
||||
- Similar completed tasks
|
||||
- Relevant learnings
|
||||
- Applicable standards
|
||||
- Recent decisions
|
||||
- Known issues
|
||||
- Code patterns
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Task Claim Flow
|
||||
|
||||
```
|
||||
Agent claims task
|
||||
|
|
||||
v
|
||||
+-------------------+
|
||||
| ProactiveContext |
|
||||
| Service |
|
||||
+-------------------+
|
||||
|
|
||||
+-- Search similar tasks (completed)
|
||||
+-- Search relevant learnings
|
||||
+-- Get applicable standards
|
||||
+-- Get recent decisions
|
||||
+-- Search known issues
|
||||
|
|
||||
v
|
||||
Context injected into task.proactive_context
|
||||
|
|
||||
v
|
||||
Agent receives context on task start
|
||||
```
|
||||
|
||||
### Learning Flow
|
||||
|
||||
```
|
||||
Agent discovers insight
|
||||
|
|
||||
v
|
||||
roboco_record_learning()
|
||||
|
|
||||
v
|
||||
+-------------------+
|
||||
| OptimalService |
|
||||
+-------------------+
|
||||
|
|
||||
+-- Store in PostgreSQL
|
||||
+-- Index in pgvector (learnings index)
|
||||
+-- Optionally notify similar-role agents
|
||||
|
|
||||
v
|
||||
Future agents find via search
|
||||
```
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Location:** `roboco/mcp/optimal_server.py`
|
||||
|
||||
**Tool Groups:**
|
||||
|
||||
| Group | Tools |
|
||||
|-------|-------|
|
||||
| Search | `kb_search`, `rag_query`, `kb_stats` |
|
||||
| Indexing | `kb_index_code`, `kb_index_docs` |
|
||||
| Mentor | `ask_mentor` |
|
||||
| Errors | `search_error`, `record_error_solution` |
|
||||
| Decisions | `check_decision`, `record_decision` |
|
||||
| Standards | `get_standards`, `validate_action`, `review_code` |
|
||||
| Learning | `record_learning`, `search_learnings` |
|
||||
| Context | `get_proactive_context` |
|
||||
| Admin | `clear_index`, `reindex_all`, `index_status` |
|
||||
|
||||
## API Endpoints
|
||||
|
||||
**Location:** `roboco/api/routes/optimal.py`
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
|----------|--------|---------|
|
||||
| `/optimal/kb/search` | POST | Semantic search |
|
||||
| `/optimal/rag/query` | POST | RAG answer |
|
||||
| `/optimal/mentor/ask` | POST | Conversational help |
|
||||
| `/optimal/errors/search` | POST | Error lookup |
|
||||
| `/optimal/errors/record` | POST | Record solution |
|
||||
| `/optimal/decisions/check` | POST | Check precedent |
|
||||
| `/optimal/decisions/record` | POST | Record decision |
|
||||
| `/optimal/standards/get` | POST | Get standards |
|
||||
| `/optimal/standards/validate` | POST | Validate action |
|
||||
| `/optimal/review/code` | POST | Code review |
|
||||
| `/optimal/learnings/record` | POST | Record learning |
|
||||
| `/optimal/learnings/search` | POST | Search learnings |
|
||||
| `/optimal/context/proactive` | POST | Get context |
|
||||
| `/optimal/stats` | GET | Index stats |
|
||||
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
# Embedding model (local)
|
||||
ROBOCO_DEFAULT_EMBEDDING_MODEL=qwen3-embedding:0.6b
|
||||
|
||||
# LLM for RAG synthesis
|
||||
ROBOCO_LOCAL_LLM_MODEL=glm-4.7:cloud
|
||||
ROBOCO_LOCAL_LLM_BASE_URL=http://roboco-ollama:11434/v1
|
||||
|
||||
# RAG settings
|
||||
ROBOCO_RAG_CHUNK_STRATEGY=fixed
|
||||
ROBOCO_RAG_CHUNK_SIZE=512
|
||||
ROBOCO_RAG_USE_HYDE=true
|
||||
ROBOCO_RAG_USE_HYBRID_SEARCH=true
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Ask mentor first** - `roboco_ask_mentor` is the primary tool
|
||||
2. **Check before deciding** - Use `roboco_check_decision`
|
||||
3. **Record solutions** - Use `roboco_record_error_solution`
|
||||
4. **Share learnings** - Use `roboco_record_learning`
|
||||
5. **Validate actions** - Use `roboco_validate_action`
|
||||
@@ -0,0 +1,120 @@
|
||||
# Cross-Agent Learning
|
||||
|
||||
When one agent learns something, all agents benefit. The learning network enables organizational knowledge to compound over time.
|
||||
|
||||
## Recording Learnings
|
||||
|
||||
When you discover something useful, record it:
|
||||
|
||||
```python
|
||||
roboco_record_learning(
|
||||
content="Use transactions for multi-table updates to prevent partial writes",
|
||||
category="pattern",
|
||||
team="backend", # Optional: backend, frontend, ux_ui
|
||||
shareable=True, # Default: True
|
||||
tags=["database", "transactions", "consistency"]
|
||||
)
|
||||
```
|
||||
|
||||
## Learning Categories
|
||||
|
||||
| Category | When to Use |
|
||||
|----------|-------------|
|
||||
| `error_handling` | How to handle specific errors |
|
||||
| `performance` | Optimization techniques |
|
||||
| `testing` | Testing strategies and patterns |
|
||||
| `pattern` | Code patterns and idioms |
|
||||
| `architecture` | Design decisions and trade-offs |
|
||||
| `security` | Security best practices |
|
||||
| `workflow` | Process improvements |
|
||||
| `tooling` | Tool usage tips |
|
||||
|
||||
## Searching Learnings
|
||||
|
||||
Before starting work, check what others learned:
|
||||
|
||||
```python
|
||||
roboco_search_learnings(
|
||||
query="database connection pooling",
|
||||
category="performance", # Optional filter
|
||||
team="backend", # Optional filter
|
||||
top_k=10
|
||||
)
|
||||
```
|
||||
|
||||
## What to Record
|
||||
|
||||
**DO record:**
|
||||
- Solutions to tricky problems
|
||||
- Performance optimizations discovered
|
||||
- Security patterns you implemented
|
||||
- Testing strategies that worked
|
||||
- Workflow improvements
|
||||
- Tool configurations that helped
|
||||
|
||||
**DON'T record:**
|
||||
- Obvious/basic knowledge
|
||||
- Temporary workarounds
|
||||
- Context-specific hacks
|
||||
- Personal preferences
|
||||
|
||||
## Good Learning Examples
|
||||
|
||||
```python
|
||||
# Specific and actionable
|
||||
roboco_record_learning(
|
||||
content="Redis SCAN is O(N) total but O(1) per call. Use SCAN over KEYS for large datasets.",
|
||||
category="performance",
|
||||
tags=["redis", "scan", "keys"]
|
||||
)
|
||||
|
||||
# Pattern with context
|
||||
roboco_record_learning(
|
||||
content="Use circuit breakers for external API calls. Implemented in services/http_client.py:42",
|
||||
category="pattern",
|
||||
tags=["resilience", "circuit-breaker", "api"]
|
||||
)
|
||||
|
||||
# Security insight
|
||||
roboco_record_learning(
|
||||
content="Always validate file uploads server-side. Client validation is insufficient.",
|
||||
category="security",
|
||||
tags=["upload", "validation"]
|
||||
)
|
||||
```
|
||||
|
||||
## Learning Flow
|
||||
|
||||
```
|
||||
Agent solves problem
|
||||
|
|
||||
v
|
||||
roboco_record_learning()
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| Indexed in KB |
|
||||
+------------------+
|
||||
|
|
||||
+-- Available via roboco_search_learnings()
|
||||
+-- Included in roboco_ask_mentor() responses
|
||||
+-- Injected in proactive context for similar tasks
|
||||
|
|
||||
v
|
||||
Future agents benefit
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Record immediately** - Don't wait, you'll forget details
|
||||
2. **Be specific** - Include file paths, function names
|
||||
3. **Add context** - Why does this matter?
|
||||
4. **Tag appropriately** - Helps future discovery
|
||||
5. **Search first** - Before solving, check if someone already did
|
||||
|
||||
## Team vs Org Scope
|
||||
|
||||
- `team` filter: Learnings from your cell (backend/frontend/ux_ui)
|
||||
- No filter: Learnings from entire organization
|
||||
|
||||
Cross-team learnings are often valuable - security and performance insights apply everywhere.
|
||||
@@ -0,0 +1,114 @@
|
||||
# Proactive Knowledge Injection
|
||||
|
||||
System automatically provides relevant context when you claim a task.
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
You claim task --> System searches KB --> Context injected --> You start informed
|
||||
```
|
||||
|
||||
When you claim a task, the system:
|
||||
1. Searches for similar completed tasks
|
||||
2. Finds relevant learnings from other agents
|
||||
3. Gets applicable coding/security standards
|
||||
4. Retrieves recent architectural decisions
|
||||
5. Identifies known issues in related areas
|
||||
6. Finds relevant code patterns
|
||||
|
||||
## Getting Context
|
||||
|
||||
```python
|
||||
# Context is auto-stored on task claim
|
||||
# Retrieve it when starting work:
|
||||
roboco_get_proactive_context(task_id="your-task-id")
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `similar_tasks` | Completed tasks with similar descriptions |
|
||||
| `relevant_learnings` | Insights from other agents |
|
||||
| `applicable_standards` | Rules that apply to this work |
|
||||
| `recent_decisions` | Related architectural choices |
|
||||
| `known_issues` | Problems to watch out for |
|
||||
| `code_patterns` | Relevant code examples |
|
||||
| `summary` | AI-generated context summary |
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"source": "stored",
|
||||
"similar_tasks": [
|
||||
{
|
||||
"id": "abc-123",
|
||||
"title": "Add user authentication",
|
||||
"completion_notes": "Used JWT with refresh tokens"
|
||||
}
|
||||
],
|
||||
"relevant_learnings": [
|
||||
{
|
||||
"content": "Always validate JWT expiry server-side",
|
||||
"agent": "be-dev-1",
|
||||
"category": "security"
|
||||
}
|
||||
],
|
||||
"applicable_standards": [
|
||||
{
|
||||
"rule": "Use Pydantic for request validation",
|
||||
"severity": "required"
|
||||
}
|
||||
],
|
||||
"summary": "Similar auth work done. Use JWT pattern from task abc-123."
|
||||
}
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Claim Task
|
||||
|
||||
```python
|
||||
roboco_task_claim(task_id="my-task")
|
||||
# System auto-generates proactive context
|
||||
```
|
||||
|
||||
### 2. Start Work
|
||||
|
||||
```python
|
||||
# Get the context that was prepared for you
|
||||
context = roboco_get_proactive_context(task_id="my-task")
|
||||
|
||||
# Review what's relevant
|
||||
print(context["summary"])
|
||||
print(context["similar_tasks"])
|
||||
```
|
||||
|
||||
### 3. Apply Knowledge
|
||||
|
||||
Use the context to:
|
||||
- Avoid repeating past mistakes
|
||||
- Follow established patterns
|
||||
- Build on previous decisions
|
||||
- Learn from others' experiences
|
||||
|
||||
## Force Refresh
|
||||
|
||||
If context seems stale:
|
||||
|
||||
```python
|
||||
roboco_get_proactive_context(
|
||||
task_id="my-task",
|
||||
force_refresh=True # Skip stored, generate fresh
|
||||
)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always check context** when starting a task
|
||||
2. **Read similar tasks** - learn from past work
|
||||
3. **Note applicable standards** - avoid violations
|
||||
4. **Check known issues** - prevent repeating problems
|
||||
5. **Review learnings** - benefit from others' insights
|
||||
@@ -0,0 +1,163 @@
|
||||
# Rule Enforcement
|
||||
|
||||
Validate actions against organizational standards before executing.
|
||||
|
||||
## Pre-Action Validation
|
||||
|
||||
Before taking significant actions, check for applicable rules:
|
||||
|
||||
```python
|
||||
roboco_validate_action(
|
||||
action_type="create_endpoint",
|
||||
context="Adding POST /users endpoint with email/password"
|
||||
)
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "validated",
|
||||
"allowed": true,
|
||||
"violations": [],
|
||||
"warnings": ["Consider rate limiting for auth endpoints"],
|
||||
"relevant_standards": [
|
||||
{"rule": "Use Pydantic for request validation", "severity": "required"},
|
||||
{"rule": "Return 201 for successful creates", "severity": "recommended"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Getting Standards
|
||||
|
||||
Retrieve standards before writing code:
|
||||
|
||||
```python
|
||||
# Get coding standards for Python
|
||||
roboco_get_standards(domain="coding", language="python")
|
||||
|
||||
# Get security standards
|
||||
roboco_get_standards(domain="security")
|
||||
|
||||
# Get workflow standards
|
||||
roboco_get_standards(domain="workflow")
|
||||
```
|
||||
|
||||
## Standard Domains
|
||||
|
||||
| Domain | Covers |
|
||||
|--------|--------|
|
||||
| `coding` | Style, patterns, naming, structure |
|
||||
| `security` | OWASP, auth, input validation |
|
||||
| `workflow` | Task lifecycle, handoffs, reviews |
|
||||
| `testing` | Coverage, patterns, mocking |
|
||||
| `api` | REST conventions, versioning |
|
||||
| `git` | Branching, commits, PRs |
|
||||
|
||||
## Code Review
|
||||
|
||||
Get automated feedback before committing:
|
||||
|
||||
```python
|
||||
roboco_review_code(
|
||||
code="""
|
||||
def create_user(email: str, password: str):
|
||||
user = User(email=email, password=password)
|
||||
db.add(user)
|
||||
return user
|
||||
""",
|
||||
file_path="api/users.py",
|
||||
change_type="add" # add, modify, delete
|
||||
)
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "reviewed",
|
||||
"approved": false,
|
||||
"score": 65,
|
||||
"comments": [
|
||||
{
|
||||
"line": 2,
|
||||
"severity": "error",
|
||||
"message": "Password must be hashed before storage"
|
||||
},
|
||||
{
|
||||
"line": 1,
|
||||
"severity": "warning",
|
||||
"message": "Add Pydantic model for input validation"
|
||||
}
|
||||
],
|
||||
"standards_checked": ["security-passwords", "api-validation"]
|
||||
}
|
||||
```
|
||||
|
||||
## Action Types
|
||||
|
||||
Common action types for validation:
|
||||
|
||||
| Action Type | Description |
|
||||
|-------------|-------------|
|
||||
| `create_endpoint` | Adding API endpoint |
|
||||
| `add_dependency` | Adding package/library |
|
||||
| `database_migration` | Schema changes |
|
||||
| `auth_change` | Authentication/authorization |
|
||||
| `env_config` | Environment configuration |
|
||||
| `file_upload` | File upload handling |
|
||||
| `external_api` | External API integration |
|
||||
|
||||
## Workflow
|
||||
|
||||
### Before Writing Code
|
||||
|
||||
```python
|
||||
# 1. Get applicable standards
|
||||
standards = roboco_get_standards(domain="coding", language="python")
|
||||
|
||||
# 2. Review the rules
|
||||
for s in standards["standards"]:
|
||||
print(f"[{s['severity']}] {s['rule']}")
|
||||
```
|
||||
|
||||
### Before Committing
|
||||
|
||||
```python
|
||||
# 1. Validate the action
|
||||
result = roboco_validate_action(
|
||||
action_type="create_endpoint",
|
||||
context=my_code
|
||||
)
|
||||
|
||||
# 2. Check for violations
|
||||
if not result["allowed"]:
|
||||
for v in result["violations"]:
|
||||
print(f"VIOLATION: {v}")
|
||||
# Fix before proceeding
|
||||
|
||||
# 3. Get code review
|
||||
review = roboco_review_code(code=my_code, file_path="api/endpoint.py")
|
||||
|
||||
# 4. Address comments
|
||||
if not review["approved"]:
|
||||
for c in review["comments"]:
|
||||
print(f"[{c['severity']}] Line {c['line']}: {c['message']}")
|
||||
```
|
||||
|
||||
## Severity Levels
|
||||
|
||||
| Level | Meaning |
|
||||
|-------|---------|
|
||||
| `required` | Must follow, blocks merge |
|
||||
| `recommended` | Should follow, may warn |
|
||||
| `optional` | Nice to have |
|
||||
| `deprecated` | Being phased out |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Check standards first** - Before writing, know the rules
|
||||
2. **Validate before commit** - Catch issues early
|
||||
3. **Review your code** - Automated feedback helps
|
||||
4. **Fix violations** - Don't ignore required rules
|
||||
5. **Address warnings** - They often prevent future issues
|
||||
Reference in New Issue
Block a user