External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add Optimal Brain architecture and workflow documentation

Browse Source 
- 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
2026-01-30 12:20:48 +00:00
parent 8481d0c46c
commit 20be420ab6
4 changed files with 658 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/rag/architecture/optimal-brain.md
+261
View File
@@ -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`
docs/rag/workflows/cross-agent-learning.md
+120
View File
@@ -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.
docs/rag/workflows/proactive-knowledge.md
+114
View File
@@ -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
docs/rag/workflows/rule-enforcement.md
+163
View File
@@ -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