← Documentation Home

Agent Brain - Development Guide

Overview

This guide covers local development setup, testing workflows, and contribution guidelines for the Agent Brain cognitive orchestration system.

Prerequisites

Required Software

Local Development Setup

1. Clone Repository

git clone https://gitlab.bluefly.io/llm/npm/agent-buildkit.git
cd agent-buildkit

2. Install Dependencies

# Install Node.js dependencies
npm install

# Install Python dependencies (MCP server)
cd mcp-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ..

3. Environment Configuration

Create .env file in project root:

# GitLab Integration
GITLAB_URL=https://gitlab.bluefly.io
GITLAB_TOKEN=your-gitlab-personal-access-token
GITLAB_PROJECT_ID=llm/agent-buildkit

# Neo4j Knowledge Graph
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-neo4j-password

# Qdrant Vector Storage
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-qdrant-api-key

# Redis (locks and cache)
REDIS_URL=redis://localhost:6379

# Sequential Thinking
SEQUENTIAL_THINKING_STORAGE=/Users/you/agent-buildkit/.agents/data/sequential-thinking

# Phoenix Arize (optional)
PHOENIX_API_KEY=your-phoenix-api-key
PHOENIX_PROJECT_NAME=agent-buildkit-dev

# Observability (optional)
PROMETHEUS_URL=http://localhost:9090
GRAFANA_URL=http://localhost:3001

# Node Environment
NODE_ENV=development

4. Start Local Services

Option A: Docker Compose (Recommended)

# Start all services
docker-compose -f infra/docker-compose.orchestrator.yml up -d

# Services started:
# - Neo4j: http://localhost:7474 (bolt://localhost:7687)
# - Qdrant: http://localhost:6333
# - Redis: localhost:6379
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3001

Option B: Manual Service Start

# Neo4j
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:5.0

# Qdrant
docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  qdrant/qdrant:v1.7.0

# Redis
docker run -d --name redis \
  -p 6379:6379 \
  redis:7-alpine

5. Initialize Knowledge Graph

# Build CLI
npm run build:cli

# Initialize Neo4j schema
buildkit gitlab-kg build --project llm/agent-buildkit

# Create Qdrant collections
buildkit qdrant collection create --name agent_embeddings --vector-size 384
buildkit qdrant collection create --name issue_embeddings --vector-size 384
buildkit qdrant collection create --name thought_embeddings --vector-size 384

6. Verify Setup

# Check services
docker ps

# Test Neo4j connection
curl http://localhost:7474

# Test Qdrant connection
curl http://localhost:6333/collections

# Test Redis connection
redis-cli ping

# Run health checks
buildkit orchestration status

Development Workflows

Running the Development Server

# Start TypeScript development server with hot reload
npm run dev

# Start specific services
npm run viz:dev           # Visualization dashboard
npm run ecosystem:dev     # Ecosystem API server
npm run daemon:dev        # Docs-roadmap sync daemon

Sequential Thinking MCP Server

# Setup MCP server (one-time)
npm run thinking:setup

# Start MCP server
cd mcp-server
source venv/bin/activate
python sequential-thinking-mcp.py

CLI Development

# Build CLI
npm run build:cli

# Test CLI commands
buildkit thinking --help
buildkit orchestration --help
buildkit gitlab-kg --help

# Run specific commands
buildkit thinking create-session --name "Test Session" --project llm/agent-buildkit
buildkit orchestration status --detailed

IDE Integration Testing

# Configure all IDEs
buildkit thinking configure-ide all

# Configure specific IDE
buildkit thinking configure-ide cursor

# Verify IDE configs
buildkit thinking configure-ide --verify

# List configured IDEs
buildkit thinking configure-ide --list

Testing

Unit Tests

# Run all unit tests
npm test

# Run specific test file
npm test tests/services/knowledge-graph.service.test.ts

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Integration Tests

# Run integration tests (requires running services)
npm run test:integration

# Run with verbose output
npm run test:integration:verbose

# Integration test coverage
npm run test:integration:coverage

Test Structure

tests/
├── unit/
│   ├── services/
│   │   ├── knowledge-graph.service.test.ts
│   │   ├── neo4j-kg.service.test.ts
│   │   ├── qdrant.service.test.ts
│   │   └── sequential-thinking.service.test.ts
│   ├── orchestrators/
│   │   ├── task-assignment.test.ts
│   │   └── swarm-orchestrator.test.ts
│   └── utils/
│       └── decision-engine.test.ts
├── integration/
│   ├── gitlab-kg-sync.test.ts
│   ├── agent-orchestration.test.ts
│   └── knowledge-graph-queries.test.ts
└── fixtures/
    ├── agents.json
    ├── issues.json
    └── milestones.json

Writing Tests

Unit Test Example:

// tests/unit/services/knowledge-graph.service.test.ts
import { KnowledgeGraphService } from '../../../src/services/knowledge-graph.service';

describe('KnowledgeGraphService', () => {
  let service: KnowledgeGraphService;

  beforeEach(() => {
    service = new KnowledgeGraphService();
  });

  describe('findAgentsByCapability', () => {
    it('should return agents with matching capabilities', async () => {
      const agents = await service.findAgentsByCapability({
        requiredCapabilities: ['ml-inference'],
        status: 'active',
      });

      expect(agents).toBeDefined();
      expect(agents.length).toBeGreaterThan(0);
      expect(agents[0]).toHaveProperty('capabilities');
    });
  });
});

Integration Test Example:

// tests/integration/gitlab-kg-sync.test.ts
import { GitLabKnowledgeGraphService } from '../../src/services/gitlab-kg.service';

describe('GitLab Knowledge Graph Sync', () => {
  let service: GitLabKnowledgeGraphService;

  beforeAll(async () => {
    service = new GitLabKnowledgeGraphService();
    await service.initialize();
  });

  it('should sync GitLab project to knowledge graph', async () => {
    const result = await service.syncProject({
      projectId: 'llm/agent-buildkit',
      incremental: false,
    });

    expect(result.success).toBe(true);
    expect(result.nodesCreated).toBeGreaterThan(0);
    expect(result.relationshipsCreated).toBeGreaterThan(0);
  });
});

Code Quality

Linting

# Run ESLint
npm run lint

# Fix linting issues
npm run lint:fix

# Lint architecture
npm run lint:architecture

Type Checking

# Run TypeScript type checker
npm run typecheck

# Incremental type checking (faster)
npm run typecheck:incremental

# Check type coverage
npm run type:coverage

Code Formatting

# Format all files
npm run format

# Check formatting (CI)
npm run format:check

Dependency Validation

# Validate dependency graph
npm run validate:dependencies

# Validate architecture compliance
npm run validate:architecture

# Find unused exports
npm run unused:exports

# Find unused code
npm run unused:code

Building & Compiling

Standard Build

# Build all TypeScript
npm run build

# Build specific components
npm run build:cli           # CLI only
npm run build:mcp-cli       # MCP CLI
npm run build:langflow-cli  # Langflow CLI

# Clean build artifacts
npm run clean

Generate Types from OpenAPI

# Generate all types
npm run generate

# Generate specific types
npm run generate:sequential-thinking-types
npm run generate:gitlab-integration-types
npm run generate:wiki-types

Validate OpenAPI Specs

# Validate all specs
npm run validate:specs

# Generate API docs from specs
npm run docs:generate

Debugging

Debug CLI Commands

# Enable debug logging
DEBUG=* buildkit thinking start --project llm/agent-buildkit

# Debug specific modules
DEBUG=buildkit:orchestration buildkit orchestration status
DEBUG=buildkit:neo4j buildkit gitlab-kg build

Debug MCP Server

# Run MCP server with debug output
cd mcp-server
source venv/bin/activate
DEBUG=1 python sequential-thinking-mcp.py

Debug with VS Code

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug CLI",
      "runtimeArgs": ["-r", "ts-node/register"],
      "args": ["${workspaceFolder}/src/cli/index.ts", "thinking", "start"],
      "cwd": "${workspaceFolder}",
      "env": {
        "NODE_ENV": "development"
      }
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": ["--runInBand", "--no-cache"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

Inspect Neo4j Queries

# Enable Neo4j query logging
NEO4J_DEBUG=1 buildkit gitlab-kg query "MATCH (a:Agent) RETURN a"

# View Neo4j logs
docker logs neo4j -f

Inspect Qdrant Operations

# Enable Qdrant debug logging
QDRANT_DEBUG=1 buildkit qdrant search --collection agent_embeddings --query "ML agent"

# View Qdrant logs
docker logs qdrant -f

Contributing

Branch Workflow

# Create feature branch
git checkout -b feature/add-new-capability

# Make changes and commit
git add .
git commit -m "feat: add new capability for agent selection"

# Push to GitLab
git push origin feature/add-new-capability

# Create merge request on GitLab

Commit Message Format

Follow Conventional Commits:

feat: add agent capability matching algorithm
fix: resolve Neo4j connection pool leak
docs: update knowledge graph schema documentation
test: add integration tests for sequential thinking
refactor: simplify orchestration service logic
chore: update dependencies

Pre-commit Hooks

Hooks are managed by Lefthook (.lefthook.yml):

pre-commit:
  commands:
    lint:
      run: npm run lint
    typecheck:
      run: npm run typecheck
    test:
      run: npm test

Code Review Checklist

Documentation Standards

Troubleshooting

Common Issues

Issue: Neo4j connection refused

# Check Neo4j is running
docker ps | grep neo4j

# Check Neo4j logs
docker logs neo4j

# Restart Neo4j
docker restart neo4j

Issue: Qdrant collection not found

# List collections
buildkit qdrant collection list

# Create missing collection
buildkit qdrant collection create --name agent_embeddings --vector-size 384

Issue: Redis connection timeout

# Check Redis is running
docker ps | grep redis

# Test Redis connection
redis-cli ping

# Restart Redis
docker restart redis

Issue: MCP server not starting

# Check Python environment
cd mcp-server
source venv/bin/activate
python --version

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Check for port conflicts
lsof -i :3000

Issue: GitLab API rate limiting

# Check rate limit status
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" https://gitlab.bluefly.io/api/v4/user

# Use incremental sync to reduce API calls
buildkit gitlab-kg sync --incremental

Performance Profiling

# Profile TypeScript execution
node --prof dist/cli/index.js thinking start

# Profile Neo4j queries
NEO4J_PROFILE=1 buildkit gitlab-kg query "MATCH (a:Agent) RETURN a"

# Monitor memory usage
node --inspect dist/cli/index.js thinking start

Deployment

Docker Build

# Build orchestrator image
npm run container:build

# Build local variant
npm run container:build:local

# Start containers
npm run container:up

# View logs
npm run container:logs

Kubernetes Deployment

# Deploy to Kubernetes
helm install agent-buildkit charts/agents -n agents

# Check deployment status
kubectl get pods -n agents

# View logs
kubectl logs -n agents -l app=agent-buildkit -f

# Port forward to access locally
kubectl port-forward -n agents svc/agent-buildkit 3000:3000

OrbStack (macOS)

# Route agent via OrbStack
buildkit orbstack route-agent

# Auto-scale based on load
buildkit orbstack auto-scale

# Monitor OrbStack agents
buildkit orbstack monitor

Useful Commands

GitLab Knowledge Graph

# Build complete graph
buildkit gitlab-kg build --project llm/agent-buildkit

# Incremental sync
buildkit gitlab-kg sync --incremental

# Query graph
buildkit gitlab-kg query "MATCH (a:Agent) RETURN a LIMIT 10"

# Find related issues
buildkit gitlab-kg related --issue-id 123

# Assign opportunities
buildkit gitlab-kg assign-opportunities --agent-id worker-001

# Export graph
buildkit gitlab-kg export --format graphml --output graph.graphml

Orchestration Management

# Start orchestration
buildkit orchestration start --replicas 5

# Check status
buildkit orchestration status --detailed

# Scale agents
buildkit orchestration scale --agents 10

# Claim issue
buildkit orchestration issue claim --issue-id 123 --agent-id worker-001

# Inspect locks
buildkit orchestration locks inspect --verbose

# Monitor dashboard
buildkit orchestration monitor dashboard

Sequential Thinking

# Configure IDEs
buildkit thinking configure-ide all

# Start autonomous orchestration
buildkit thinking start --project llm/agent-buildkit

# Create session
buildkit thinking create-session --name "Feature Planning" --project llm/agent-buildkit

# List agents
buildkit thinking list-agents

# Spawn agent
buildkit thinking spawn-agent --name "Worker" --type worker --project llm/agent-buildkit

Resources

Support

Last Updated: 2025-11-02 Development Guide Version: v0.1.2