Development Guide

This guide covers development practices, testing, debugging, and contributing to YAAAF.

Development Environment

Prerequisites

System Requirements:

Python 3.11+
Node.js 18+
Git
pnpm (for frontend)
Ollama (for LLM)

Recommended Tools:

VSCode or PyCharm
Python debugger
Browser developer tools
Database browser (for SQLite)

Setting Up Development Environment

Clone Repository:

git clone <repository-url>
cd agents_framework

Backend Setup:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Frontend Setup:

cd frontend
pnpm install
pnpm build:registry

Development Database:

# Create test database or use existing one
sqlite3 data/test.db < schema.sql

Code Style and Standards

Python Standards

Code Formatting:

Use ruff for formatting and linting:

ruff format .        # Format code
ruff check .         # Check for issues
ruff check . --fix   # Auto-fix issues

Type Hints:

All Python code should include type hints:

def process_query(messages: Messages, timeout: Optional[int] = None) -> str:
    """Process a query with optional timeout."""
    return result

Docstrings:

Use Google-style docstrings:

def create_agent(name: str, config: Dict[str, Any]) -> BaseAgent:
    """Create a new agent instance.

    Args:
        name: The name of the agent to create
        config: Configuration dictionary for the agent

    Returns:
        BaseAgent: The configured agent instance

    Raises:
        ValueError: If agent name is not recognized
    """

Imports:

Organize imports according to PEP8:

# Standard library
import os
import sys
from typing import List, Optional

# Third-party
import pandas as pd
from pydantic import BaseModel

# Local imports
from yaaaf.components.agents.base_agent import BaseAgent
from yaaaf.components.data_types import Messages

TypeScript/Frontend Standards

Code Formatting:

Use Prettier and ESLint:

pnpm lint           # Check linting
pnpm format:check   # Check formatting
pnpm format:write   # Apply formatting

Type Safety:

Ensure all TypeScript code is properly typed:

interface ChatMessage {
  id: string
  content: string
  role: 'user' | 'assistant'
  timestamp: Date
  agentName?: string
}

Component Structure:

Follow consistent component patterns:

interface ComponentProps {
  title: string
  onAction?: () => void
}

export function Component({ title, onAction }: ComponentProps) {
  return (
    <div>
      <h1>{title}</h1>
      {onAction && <button onClick={onAction}>Action</button>}
    </div>
  )
}

Testing

Backend Testing

Unit Tests:

Use Python’s unittest framework:

import unittest
from yaaaf.components.agents.sql_agent import SqlAgent

class TestSqlAgent(unittest.TestCase):
    def setUp(self):
        self.agent = SqlAgent(mock_client, mock_source)

    def test_query_processing(self):
        messages = Messages().add_user_utterance("Get user count")
        result = asyncio.run(self.agent.query(messages))
        self.assertIn("SELECT", result)

Running Tests:

# Run all tests
python -m unittest discover tests/

# Run specific test
python -m unittest tests.test_sql_agent

# Run with coverage
coverage run -m unittest discover tests/
coverage report

Test Structure:

tests/
├── test_agents/
│   ├── test_base_agent.py
│   ├── test_sql_agent.py
│   └── test_orchestrator_agent.py
├── test_data_types/
│   ├── test_messages.py
│   └── test_notes.py
└── test_server/
    ├── test_routes.py
    └── test_accessories.py

Frontend Testing

Jest Testing:

cd frontend
pnpm test           # Run tests
pnpm test:watch     # Watch mode
pnpm test:coverage  # With coverage

Component Testing:

import { render, screen } from '@testing-library/react'
import { Chat } from '@/components/chat'

describe('Chat Component', () => {
  it('renders chat interface', () => {
    render(<Chat />)
    expect(screen.getByRole('textbox')).toBeInTheDocument()
  })
})

Integration Testing

End-to-End Tests:

Test complete workflows:

class TestIntegration(unittest.TestCase):
    def test_complete_query_flow(self):
        # Test: User query -> Orchestrator -> SQL Agent -> Response
        orchestrator = build_orchestrator()
        messages = Messages().add_user_utterance("How many users?")

        response = asyncio.run(orchestrator.query(messages))
        self.assertIn("users", response.lower())

Debugging

Backend Debugging

Logging Setup:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

Debug Configuration:

# Enable debug mode
import os
os.environ['YAAAF_DEBUG'] = 'true'

Common Debug Points:

Agent query processing
Message routing in orchestrator
Artifact creation and storage
Database connection issues

Frontend Debugging

Browser DevTools:

Use React Developer Tools
Monitor Network tab for API calls
Check Console for errors
Use Sources tab for breakpoints

Debug Logging:

console.log('Processing note:', note)
console.error('API call failed:', error)
console.debug('State update:', newState)

Common Issues:

API connectivity problems
State management issues
Component rendering problems
TypeScript type errors

Performance Monitoring

Backend Performance

Timing Decorators:

import time
import functools

def timing_decorator(func):
    @functools.wraps(func)
    async def wrapper(*args, **kwargs):
        start = time.time()
        result = await func(*args, **kwargs)
        duration = time.time() - start
        logger.info(f"{func.__name__} took {duration:.2f}s")
        return result
    return wrapper

Memory Monitoring:

import psutil
import os

def log_memory_usage():
    process = psutil.Process(os.getpid())
    memory_mb = process.memory_info().rss / 1024 / 1024
    logger.info(f"Memory usage: {memory_mb:.1f} MB")

Frontend Performance

React DevTools Profiler:: Use the Profiler tab to identify slow components

Web Vitals:

import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals'

getCLS(console.log)
getFID(console.log)
getFCP(console.log)
getLCP(console.log)
getTTFB(console.log)

Contributing

Git Workflow

Branch Naming:

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation updates
refactor/description - Code refactoring

Commit Messages:

Use conventional commit format:

feat: add new RAG agent for document retrieval
fix: resolve SQL injection vulnerability in queries
docs: update API documentation for new endpoints
refactor: simplify orchestrator agent routing logic

Pull Request Process:

Create Feature Branch:

git checkout -b feature/new-agent-type
git commit -m "feat: implement new agent type"
git push origin feature/new-agent-type

Create Pull Request: * Provide clear description * Include test coverage * Update documentation * Follow code review feedback

Code Review Guidelines

Review Checklist:

Code follows style guidelines
Tests are included and passing
Documentation is updated
No security vulnerabilities
Performance implications considered

Review Process:

At least one reviewer required
All tests must pass
Documentation must be updated
Security review for sensitive changes

Documentation

API Documentation:: Update docstrings and API reference when adding new features
User Documentation:: Update guides and examples for user-facing changes
Code Comments:: Add comments for complex logic or business rules

Release Process

Version Management

Semantic Versioning:

MAJOR.MINOR.PATCH format
Major: Breaking changes
Minor: New features (backward compatible)
Patch: Bug fixes

Release Branches:

git checkout -b release/1.2.0
# Update version numbers
# Final testing
git tag v1.2.0
git push origin v1.2.0

Deployment

Backend Deployment:

# Production deployment
python -m yaaaf backend 4000

# With production config
YAAAF_CONFIG=production.json python -m yaaaf backend

Frontend Deployment:

cd frontend
pnpm build
pnpm start

Docker Deployment:

# Backend Dockerfile
FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "-m", "yaaf", "backend", "4000"]

Best Practices

Security

Input Validation: Validate all user inputs
SQL Injection: Use parameterized queries
XSS Prevention: Sanitize HTML output
Authentication: Implement proper auth for production
Secrets Management: Use environment variables for secrets

Performance

Database Optimization: Use indexes and efficient queries
Caching: Implement appropriate caching strategies
Resource Management: Monitor memory and CPU usage
Async Operations: Use async/await for I/O operations

Maintainability

Modular Design: Keep components loosely coupled
Clear Interfaces: Define clear APIs between components
Documentation: Maintain up-to-date documentation
Testing: Achieve good test coverage
Monitoring: Implement logging and error tracking