tony/WHOOSH
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4173c0c8c87082bae8b5b70c8bb0663556128af4
WHOOSH/docs/API_SPECIFICATION.md
Claude Code 33676bae6d Add WHOOSH search service with BACKBEAT integration 
Complete implementation:
- Go-based search service with PostgreSQL and Redis backend
- BACKBEAT SDK integration for beat-aware search operations
- Docker containerization with multi-stage builds
- Comprehensive API endpoints for project analysis and search
- Database migrations and schema management
- GITEA integration for repository management
- Team composition analysis and recommendations

Key features:
- Beat-synchronized search operations with timing coordination
- Phase-based operation tracking (started → querying → ranking → completed)
- Docker Swarm deployment configuration
- Health checks and monitoring
- Secure configuration with environment variables

Architecture:
- Microservice design with clean API boundaries
- Background processing for long-running analysis
- Modular internal structure with proper separation of concerns
- Integration with CHORUS ecosystem via BACKBEAT timing

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-06 11:16:39 +10:00

1171 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# WHOOSH API Specification
## Autonomous AI Development Teams API
Auth & Scope Revision (MVP)
- Humans: authenticate via Gitea OIDC; WHOOSH should not issue long-lived user JWTs. Maintain short-lived sessions or signed service tokens as needed.
- Agents/services: use scoped service tokens (PAT-like), revocable, with minimal permissions.
- MVP endpoints: focus on tasks intake (from Gitea), team state, PR linkage/status, and a proxy for SLURP submissions. WebSocket streams are read-only status.
- Envelopes: include `version`, `schema_version`, and `request_id`. Enforce JSON Schema validation and size limits. References only (UCXL/CIDs), no large artefacts.
- Rate limiting: per token and IP, with 429 + Retry-After. Idempotency keys for mutating endpoints.
### Overview
This document defines the comprehensive API specification for WHOOSH's transformation into an Autonomous AI Development Teams orchestration platform. The API enables team formation, agent coordination, task management, and integration with CHORUS, GITEA, and SLURP systems.
## 🌐 Base Configuration
```yaml
Base URL: https://whoosh.chorus.services
API Version: v1
Authentication: Bearer JWT tokens
Content-Type: application/json
Rate Limiting: Per endpoint and role-based
WebSocket Endpoint: wss://whoosh.chorus.services/ws
```
## 🔐 Authentication
Note: Prefer OIDC for humans; if JWTs are used, scope narrowly and keep short expiry. Agents should use service tokens bound to explicit scopes.
### MVP Endpoints (v1)
- POST `/api/v1/tasks/ingest` (internal, from webhook) – accept `bzzz-task` issue payloads
- GET `/api/v1/teams/:id` – team state summary
- GET `/api/v1/teams/:id/activity` (WS) – read-only status stream
- POST `/api/v1/teams/:id/submissions` – forward to SLURP with UCXL address
- GET `/api/v1/status` – health/status
### Authentication Endpoints
```http
POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
POST /api/v1/auth/agent-register
GET /api/v1/auth/me
```
## 🎯 Team Management API
### Team Formation
#### Analyze Task and Suggest Team
```http
POST /api/v1/teams/analyze
Authorization: Bearer {token}
Content-Type: application/json
{
"task": {
"title": "Implement secure OAuth2 authentication system",
"description": "Build a complete OAuth2 authentication system with JWT tokens, user management, and social login integration",
"requirements": [
"OAuth2 specification compliance",
"Social login (Google, GitHub)",
"JWT token management",
"User profile management",
"Security best practices"
],
"repository": "https://gitea.chorus.services/projects/auth-system",
"priority": "high",
"deadline": "2025-09-10T00:00:00Z",
"estimated_complexity": "high"
},
"constraints": {
"max_team_size": 6,
"required_roles": ["security_architect"],
"preferred_agents": ["agent-security-123"],
"budget_limit": 1000,
"timeline_days": 5
}
}
Response 200:
{
"analysis_id": "analysis_7f2a8e9d",
"task_analysis": {
"complexity_score": 0.85,
"estimated_duration_hours": 120,
"risk_factors": ["security_critical", "integration_complexity"],
"required_domains": ["security", "backend", "frontend", "testing"],
"skill_requirements": {
"security": {"level": "expert", "weight": 0.4},
"backend_api": {"level": "advanced", "weight": 0.3},
"frontend_ui": {"level": "intermediate", "weight": 0.2},
"testing": {"level": "advanced", "weight": 0.1}
}
},
"recommended_team": {
"team_size": 5,
"composition": [
{
"role": "security_architect",
"required": true,
"responsibilities": ["Security requirements", "Architecture review", "Vulnerability assessment"],
"required_skills": ["oauth2", "jwt", "encryption", "security_patterns"],
"ai_model_preference": "deepseek-coder-v2:33b",
"estimated_effort_hours": 30
},
{
"role": "backend_developer",
"required": true,
"responsibilities": ["API implementation", "Database design", "Authentication logic"],
"required_skills": ["rest_api", "database", "auth_middleware"],
"ai_model_preference": "qwen2.5-coder:32b",
"estimated_effort_hours": 50
},
{
"role": "frontend_developer",
"required": true,
"responsibilities": ["Login UI", "OAuth flows", "State management"],
"required_skills": ["react", "oauth_flows", "form_validation"],
"ai_model_preference": "starcoder2:15b",
"estimated_effort_hours": 25
},
{
"role": "qa_engineer",
"required": true,
"responsibilities": ["Security testing", "Integration testing", "Automation"],
"required_skills": ["security_testing", "api_testing", "automation"],
"ai_model_preference": "phi4:14b",
"estimated_effort_hours": 15
}
],
"fallback_options": [
{
"role": "code_reviewer",
"required": false,
"responsibilities": ["Code quality", "Security review", "Best practices"],
"estimated_effort_hours": 10
}
]
},
"formation_options": {
"immediate": {
"available_agents": 4,
"formation_time_estimate": "15 minutes"
},
"optimal": {
"available_agents": 5,
"formation_time_estimate": "2 hours",
"waiting_for": ["security_architect"]
}
}
}
```
#### Create Team from Analysis
```http
POST /api/v1/teams
Authorization: Bearer {token}
Content-Type: application/json
{
"analysis_id": "analysis_7f2a8e9d",
"team_name": "Auth System Implementation Team",
"formation_strategy": "optimal", // "immediate" | "optimal" | "custom"
"gitea_settings": {
"repository": "https://gitea.chorus.services/projects/auth-system",
"create_issue": true,
"issue_template": "team_formation",
"labels": ["team:auth-system", "priority:high"]
},
"communication_settings": {
"create_p2p_channel": true,
"channel_name": "auth-system-dev-team",
"enable_hmmm": true,
"enable_voice": false
},
"quality_gates": {
"code_review_required": true,
"security_review_required": true,
"testing_threshold": 0.8,
"consensus_type": "majority"
}
}
Response 201:
{
"team_id": "team_auth_sys_001",
"team_name": "Auth System Implementation Team",
"status": "forming",
"creation_timestamp": "2025-09-03T12:30:00Z",
"gitea_issue": {
"url": "https://gitea.chorus.services/projects/auth-system/issues/42",
"issue_id": 42
},
"p2p_channel": {
"channel_id": "auth-system-dev-team",
"ucxl_address": "ucxl://auth-system:implementation-v1@team_auth_sys_001/#/"
},
"team_composition": [...], // Same as recommended_team from analysis
"agent_assignments": {
"pending": 5,
"confirmed": 0,
"recruiting": true
},
"estimated_completion": "2025-09-08T12:30:00Z"
}
```
### Team Lifecycle Management
#### Get Team Status
```http
GET /api/v1/teams/{team_id}
Authorization: Bearer {token}
Response 200:
{
"team_id": "team_auth_sys_001",
"team_name": "Auth System Implementation Team",
"status": "active", // forming | active | paused | completed | dissolved
"phase": "implementation", // planning | implementation | review | testing | integration
"created_at": "2025-09-03T12:30:00Z",
"updated_at": "2025-09-05T09:15:00Z",
"progress": {
"overall_completion": 0.65,
"milestones": {
"planning": {"status": "completed", "completion_date": "2025-09-03T18:00:00Z"},
"api_development": {"status": "in_progress", "completion": 0.8},
"ui_development": {"status": "in_progress", "completion": 0.5},
"security_review": {"status": "pending", "depends_on": ["api_development"]},
"testing": {"status": "not_started"}
}
},
"team_members": [
{
"agent_id": "agent_security_alpha",
"role": "security_architect",
"status": "active",
"joined_at": "2025-09-03T13:15:00Z",
"contribution_score": 0.95,
"current_tasks": ["Security architecture review", "OAuth2 specification compliance"]
},
{
"agent_id": "agent_backend_beta",
"role": "backend_developer",
"status": "active",
"joined_at": "2025-09-03T13:45:00Z",
"contribution_score": 0.88,
"current_tasks": ["JWT token service", "User authentication API"]
}
],
"communication": {
"p2p_channel_active": true,
"message_count": 847,
"last_activity": "2025-09-05T09:10:00Z",
"consensus_votes_pending": 2
},
"deliverables": {
"artifacts_created": 23,
"code_commits": 156,
"documentation_pages": 8,
"test_cases": 42
},
"quality_metrics": {
"code_coverage": 0.87,
"security_scan_score": 0.92,
"peer_review_score": 0.89,
"consensus_agreement_rate": 0.95
}
}
```
#### Update Team Configuration
```http
PATCH /api/v1/teams/{team_id}
Authorization: Bearer {token}
Content-Type: application/json
{
"team_name": "OAuth2 Authentication Team",
"quality_gates": {
"testing_threshold": 0.85,
"consensus_type": "supermajority"
},
"add_roles": [
{
"role": "performance_engineer",
"required": false,
"responsibilities": ["Load testing", "Performance optimization"]
}
],
"update_deadline": "2025-09-10T00:00:00Z"
}
Response 200:
{
"team_id": "team_auth_sys_001",
"updated_fields": ["team_name", "quality_gates", "roles", "deadline"],
"changes_applied": true,
"gitea_issue_updated": true,
"team_notification_sent": true
}
```
## 🤖 Agent Management API
### Agent Registration & Discovery
#### Register Agent
```http
POST /api/v1/agents/register
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"agent_id": "agent_security_gamma",
"name": "Security Specialist Gamma",
"node_id": "12D3KooWSecurityGamma123",
"endpoint": "http://192.168.1.72:11434",
"specialization": "security_expert",
"hardware_config": {
"gpu_type": "AMD Radeon RX 7900 XTX",
"vram_gb": 24,
"cpu_cores": 16,
"ram_gb": 64,
"performance_tier": "high"
},
"ai_models": [
{
"name": "deepseek-coder-v2:33b",
"type": "code_generation",
"performance_score": 0.95,
"specialties": ["security", "architecture", "code_review"]
},
{
"name": "phi4:14b",
"type": "reasoning",
"performance_score": 0.88,
"specialties": ["problem_solving", "debugging"]
}
],
"capabilities": [
{
"domain": "security",
"proficiency": 0.95,
"skills": ["oauth2", "jwt", "encryption", "vulnerability_assessment", "penetration_testing"],
"certifications": ["OWASP", "Security+"],
"experience_score": 0.92
},
{
"domain": "backend",
"proficiency": 0.78,
"skills": ["rest_api", "database_security", "auth_middleware"],
"experience_score": 0.75
}
],
"availability": {
"max_concurrent_teams": 2,
"current_load": 0.3,
"preferred_hours": "24/7",
"timezone": "UTC"
},
"collaboration_preferences": {
"communication_style": "technical_detail",
"review_thoroughness": "comprehensive",
"consensus_approach": "evidence_based"
}
}
Response 201:
{
"agent_id": "agent_security_gamma",
"registration_status": "confirmed",
"registered_at": "2025-09-03T14:20:00Z",
"assigned_tier": "expert",
"initial_reputation_score": 0.8,
"available_for_teams": true,
"next_health_check": "2025-09-03T14:25:00Z"
}
```
#### Agent Team Application
```http
POST /api/v1/agents/apply-to-team
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"agent_id": "agent_security_gamma",
"team_id": "team_auth_sys_001",
"target_role": "security_architect",
"application_reason": "I have extensive experience with OAuth2 implementations and security architecture. My specialization in authentication systems and 95% proficiency in security domain makes me ideal for this role.",
"commitment_level": "full", // full | partial | backup
"availability_window": {
"start": "2025-09-03T15:00:00Z",
"end": "2025-09-08T15:00:00Z",
"hours_per_day": 8
},
"proposed_approach": {
"security_strategy": "Defense in depth with OAuth2 best practices",
"review_checkpoints": ["Architecture", "Implementation", "Testing"],
"risk_mitigation": "Automated security scanning + manual review"
},
"references": {
"previous_teams": ["team_secure_api_v2", "team_auth_migration"],
"success_metrics": {
"completion_rate": 0.95,
"security_score_avg": 0.91,
"peer_rating_avg": 4.7
}
}
}
Response 201:
{
"application_id": "app_sec_gamma_001",
"application_status": "pending_review",
"submitted_at": "2025-09-03T14:25:00Z",
"team_notification_sent": true,
"review_deadline": "2025-09-03T18:00:00Z",
"gitea_comment_created": true,
"next_steps": [
"Team members will review your application",
"Existing security architect may interview you",
"Decision expected within 4 hours"
]
}
```
### Agent Performance & Health
#### Get Agent Status
```http
GET /api/v1/agents/{agent_id}
Authorization: Bearer {token}
Response 200:
{
"agent_id": "agent_security_gamma",
"status": "active", // offline | idle | busy | active | maintenance
"health_score": 0.94,
"last_seen": "2025-09-05T09:12:00Z",
"current_teams": [
{
"team_id": "team_auth_sys_001",
"role": "security_architect",
"joined_at": "2025-09-03T15:30:00Z",
"contribution_level": "high"
}
],
"performance_metrics": {
"current_load": 0.65,
"avg_response_time": "2.3s",
"tokens_per_second": 18.7,
"success_rate": 0.96,
"uptime_24h": 0.99
},
"reputation": {
"overall_score": 0.89,
"team_ratings": {
"collaboration": 4.8,
"technical_quality": 4.9,
"communication": 4.6,
"reliability": 4.7
},
"completed_teams": 23,
"success_rate": 0.91
},
"capabilities_assessment": {
"security": {
"current_proficiency": 0.95,
"growth_trend": "+0.02",
"recent_achievements": ["OAuth2 expert certification", "Zero-day vulnerability discovery"]
}
}
}
```
## 🔄 Task & Workflow Management
### Task Analysis
#### Submit Task for Analysis
```http
POST /api/v1/tasks/analyze
Authorization: Bearer {token}
Content-Type: application/json
{
"task": {
"title": "Migrate legacy authentication to OAuth2",
"description": "Replace custom authentication system with OAuth2, maintaining user data integrity and minimizing downtime",
"repository": "https://gitea.chorus.services/legacy/user-system",
"type": "migration", // feature | bugfix | migration | refactor | research
"priority": "high",
"urgency": "medium",
"complexity_hint": "high"
},
"context": {
"existing_system": {
"technology": "Custom PHP authentication",
"user_count": 50000,
"daily_active_users": 5000,
"security_issues": ["password_storage", "session_management"]
},
"constraints": {
"zero_downtime_required": true,
"data_migration_needed": true,
"compliance_requirements": ["GDPR", "SOC2"]
},
"success_criteria": [
"All users migrated successfully",
"No authentication downtime",
"Security audit passes",
"Performance maintained or improved"
]
}
}
Response 200:
{
"analysis_id": "task_analysis_892f3e1a",
"task_classification": {
"type": "migration",
"complexity": "high",
"risk_level": "medium-high",
"estimated_duration_hours": 200,
"confidence_score": 0.87
},
"domain_analysis": {
"primary_domains": ["security", "backend", "database"],
"secondary_domains": ["frontend", "devops", "compliance"],
"critical_success_factors": [
"Data integrity preservation",
"Zero-downtime deployment",
"Security compliance validation"
]
},
"risk_assessment": {
"high_risks": [
{
"risk": "Data loss during migration",
"probability": 0.15,
"impact": "critical",
"mitigation": "Comprehensive backup and rollback strategy"
}
],
"medium_risks": [
{
"risk": "Authentication service interruption",
"probability": 0.3,
"impact": "high",
"mitigation": "Blue-green deployment with fallback"
}
]
},
"recommended_approach": {
"strategy": "Phased migration with parallel systems",
"phases": [
{
"name": "Preparation",
"duration_hours": 40,
"activities": ["Data audit", "OAuth2 design", "Testing framework"]
},
{
"name": "Implementation",
"duration_hours": 80,
"activities": ["OAuth2 service", "Migration scripts", "Frontend updates"]
},
{
"name": "Migration",
"duration_hours": 60,
"activities": ["User migration", "System cutover", "Validation"]
},
{
"name": "Cleanup",
"duration_hours": 20,
"activities": ["Legacy system removal", "Documentation", "Post-migration audit"]
}
]
}
}
```
### Team Formation Integration
#### Create Team from Task Analysis
```http
POST /api/v1/tasks/{analysis_id}/create-team
Authorization: Bearer {token}
Content-Type: application/json
{
"team_configuration": {
"formation_speed": "optimal", // immediate | fast | optimal | thorough
"team_size_preference": "medium", // small | medium | large
"experience_level": "senior", // junior | mixed | senior | expert
"risk_tolerance": "low" // low | medium | high
},
"override_roles": {
"add_required": ["compliance_specialist", "data_migration_expert"],
"make_optional": ["frontend_developer"]
},
"constraints": {
"exclude_agents": ["agent_junior_001"],
"require_agents": ["agent_migration_expert"],
"max_budget": 5000,
"deadline": "2025-09-20T00:00:00Z"
}
}
Response 201:
{
"team_id": "team_auth_migration_v2",
"formation_status": "in_progress",
"estimated_formation_time": "45 minutes",
"team_composition": {
"total_roles": 7,
"required_roles": 5,
"optional_roles": 2,
"recruiting_status": {
"security_architect": "confirmed",
"migration_specialist": "confirmed",
"backend_developer": "pending",
"database_engineer": "recruiting",
"compliance_specialist": "recruiting",
"devops_engineer": "waitlisted",
"qa_engineer": "optional_pending"
}
},
"progress_tracking": {
"gitea_issue_created": true,
"issue_url": "https://gitea.chorus.services/legacy/user-system/issues/78",
"p2p_channel_reserved": true,
"channel_address": "ucxl://legacy:auth-migration@team_auth_migration_v2/#/"
}
}
```
## 💬 Communication & Collaboration API
### P2P Channel Management
#### Create Team Communication Channel
```http
POST /api/v1/communication/channels
Authorization: Bearer {token}
Content-Type: application/json
{
"team_id": "team_auth_sys_001",
"channel_config": {
"name": "auth-system-dev-team",
"description": "OAuth2 Authentication System Development",
"privacy": "team_only", // public | team_only | private
"features": {
"hmmm_reasoning": true,
"file_sharing": true,
"screen_sharing": false,
"voice_channels": false,
"code_collaboration": true
}
},
"topic_streams": [
{"name": "planning", "description": "Initial design discussions"},
{"name": "implementation", "description": "Development coordination"},
{"name": "review", "description": "Code and design reviews"},
{"name": "testing", "description": "QA coordination"},
{"name": "integration", "description": "Final assembly and deployment"}
],
"moderation": {
"auto_moderation": true,
"require_approval": false,
"archive_after_days": 90
}
}
Response 201:
{
"channel_id": "chan_auth_dev_7f3a2b1c",
"ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#/",
"p2p_network_id": "auth-system-dev-team",
"created_at": "2025-09-03T15:45:00Z",
"topic_streams": [
{
"stream_id": "planning_001",
"ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#planning/",
"subscribers": 0
}
],
"access_credentials": {
"team_members": "automatic",
"invitation_code": "invite_7f3a2b1c_temp",
"expires_at": "2025-09-03T23:45:00Z"
}
}
```
### HMMM Reasoning Integration
#### Submit Reasoning Chain
```http
POST /api/v1/communication/reasoning
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"channel_id": "chan_auth_dev_7f3a2b1c",
"topic_stream": "implementation",
"reasoning": {
"agent_id": "agent_security_gamma",
"context": "Evaluating JWT token storage strategies",
"thinking_process": {
"problem": "Need secure JWT storage that balances security and UX",
"options_considered": [
{
"option": "HttpOnly cookies",
"pros": ["XSS protection", "Automatic handling"],
"cons": ["CSRF vulnerability", "SPA complexity"]
},
{
"option": "Local storage",
"pros": ["Simple implementation", "SPA friendly"],
"cons": ["XSS vulnerability", "No automatic expiry"]
},
{
"option": "Memory + refresh pattern",
"pros": ["Maximum security", "Automatic cleanup"],
"cons": ["Implementation complexity", "User experience impact"]
}
],
"analysis": "Given our high security requirements and SPA architecture, recommend memory + refresh pattern with secure HttpOnly refresh tokens",
"confidence": 0.87,
"supporting_evidence": ["OWASP JWT guidelines", "Previous team experience"],
"questions_for_team": [
"Do we have requirements for offline functionality?",
"What's our tolerance for login frequency?"
]
}
},
"requesting_feedback": true,
"decision_required": true,
"related_artifacts": ["jwt_architecture_doc", "security_requirements"]
}
Response 201:
{
"reasoning_id": "reason_jwt_storage_001",
"published_at": "2025-09-05T10:30:00Z",
"ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#implementation/reason_jwt_storage_001",
"broadcast_status": "sent_to_all_members",
"team_notification": "sent",
"slurp_ingestion": "queued",
"feedback_thread": {
"thread_id": "feedback_jwt_001",
"participants_needed": ["backend_developer", "frontend_developer"],
"deadline": "2025-09-05T18:00:00Z"
}
}
```
### Consensus & Decision Making
#### Initiate Team Vote
```http
POST /api/v1/teams/{team_id}/votes
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"vote_title": "JWT Storage Strategy Decision",
"description": "Choose the JWT token storage strategy for the OAuth2 implementation",
"type": "single_choice", // single_choice | multiple_choice | approval | ranking
"consensus_threshold": "majority", // simple | majority | supermajority | unanimous
"options": [
{
"id": "option_httponly_cookies",
"title": "HttpOnly Cookies",
"description": "Store tokens in HttpOnly cookies with CSRF protection"
},
{
"id": "option_memory_refresh",
"title": "Memory + Refresh Pattern",
"description": "Keep access tokens in memory with secure refresh tokens"
},
{
"id": "option_hybrid",
"title": "Hybrid Approach",
"description": "Use memory for access tokens, HttpOnly for refresh tokens"
}
],
"voting_period": {
"duration_hours": 8,
"deadline": "2025-09-05T18:30:00Z"
},
"eligibility": {
"roles": ["security_architect", "backend_developer", "frontend_developer"],
"minimum_participation": 3
},
"context": {
"reasoning_references": ["reason_jwt_storage_001"],
"decision_impact": "critical",
"implementation_dependencies": ["api_design", "frontend_auth_flow"]
}
}
Response 201:
{
"vote_id": "vote_jwt_strategy_001",
"status": "active",
"created_at": "2025-09-05T10:30:00Z",
"voting_ends_at": "2025-09-05T18:30:00Z",
"eligible_voters": [
{
"agent_id": "agent_security_gamma",
"role": "security_architect",
"voting_weight": 1.2
},
{
"agent_id": "agent_backend_beta",
"role": "backend_developer",
"voting_weight": 1.0
}
],
"current_participation": {
"votes_cast": 0,
"participation_rate": 0.0,
"quorum_reached": false
},
"notification_sent": true
}
```
## 🎯 SLURP Integration API
### Artifact Management
#### Package Team Artifacts
```http
POST /api/v1/teams/{team_id}/artifacts/package
Authorization: Bearer {token}
Content-Type: application/json
{
"packaging_config": {
"include_reasoning": true,
"include_decisions": true,
"include_code": true,
"include_tests": true,
"include_documentation": true,
"include_metrics": true
},
"artifact_metadata": {
"title": "OAuth2 Authentication System",
"description": "Complete OAuth2 implementation with security best practices",
"version": "1.0.0",
"authors": ["team_auth_sys_001"],
"license": "MIT",
"tags": ["authentication", "oauth2", "security", "api"]
},
"quality_verification": {
"run_tests": true,
"security_scan": true,
"performance_benchmark": true,
"documentation_check": true
},
"slurp_settings": {
"visibility": "public", // private | team | organization | public
"indexing": "full", // minimal | standard | full
"preservation_level": "permanent" // temporary | standard | permanent
}
}
Response 202:
{
"packaging_job_id": "pkg_auth_sys_001_v1",
"status": "processing",
"started_at": "2025-09-08T14:20:00Z",
"estimated_completion": "2025-09-08T14:35:00Z",
"progress": {
"current_step": "collecting_artifacts",
"steps_completed": 1,
"total_steps": 8,
"completion_percentage": 12.5
},
"preview_ucxl": "ucxl://teams:oauth2-auth@team_auth_sys_001/v1.0.0/#/",
"tracking_url": "/api/v1/packaging/{packaging_job_id}/status"
}
```
#### Submit to SLURP
```http
POST /api/v1/slurp/submit
Authorization: Bearer {token}
Content-Type: application/json
{
"team_id": "team_auth_sys_001",
"packaging_job_id": "pkg_auth_sys_001_v1",
"submission_metadata": {
"submission_type": "team_deliverable",
"completion_status": "completed",
"quality_gates_passed": [
"security_review",
"code_review",
"testing",
"documentation",
"consensus_approval"
],
"team_consensus": {
"vote_id": "vote_completion_001",
"result": "unanimous_approval",
"confidence_score": 0.94
}
},
"institutional_compliance": {
"provenance_verified": true,
"secrets_clean": true,
"temporal_pin": "2025-09-08T14:30:00Z",
"decision_rationale": "Complete OAuth2 system with comprehensive security measures and team consensus approval"
}
}
Response 201:
{
"submission_id": "slurp_sub_001_v1",
"slurp_address": "ucxl://teams:oauth2-auth@team_auth_sys_001/v1.0.0/#/",
"submission_status": "accepted",
"submitted_at": "2025-09-08T14:35:00Z",
"quality_score": 0.91,
"institutional_score": 0.96,
"artifacts": {
"total_files": 45,
"code_files": 23,
"test_files": 12,
"documentation": 8,
"reasoning_chains": 34,
"decisions": 7
},
"slurp_metadata": {
"indexed": true,
"searchable": true,
"citable": true,
"preservation_status": "permanent"
}
}
```
## 🔍 Analytics & Reporting API
### Team Performance Analytics
#### Get Team Performance Metrics
```http
GET /api/v1/analytics/teams/{team_id}/performance
Authorization: Bearer {token}
Query Parameters:
- period: day | week | month | custom
- start_date: 2025-09-01T00:00:00Z
- end_date: 2025-09-08T23:59:59Z
- metrics: completion_time,quality_score,consensus_rate
Response 200:
{
"team_id": "team_auth_sys_001",
"analysis_period": {
"start": "2025-09-03T12:30:00Z",
"end": "2025-09-08T14:35:00Z",
"duration_hours": 122.08
},
"performance_metrics": {
"completion_time": {
"actual_hours": 122.08,
"estimated_hours": 120,
"efficiency_score": 0.98,
"comparison_to_similar_teams": "+2% faster"
},
"quality_metrics": {
"overall_quality_score": 0.91,
"code_quality": 0.89,
"test_coverage": 0.87,
"security_score": 0.95,
"documentation_completeness": 0.88
},
"collaboration_effectiveness": {
"consensus_rate": 0.95,
"decision_speed_avg_hours": 4.2,
"communication_frequency": 0.85,
"conflict_resolution_time_avg_hours": 1.8,
"peer_rating_average": 4.6
},
"productivity_indicators": {
"commits_per_day": 22.3,
"artifacts_created": 45,
"reasoning_chains": 34,
"decisions_made": 7,
"milestones_achieved": 4
}
},
"team_dynamics": {
"most_active_agent": "agent_security_gamma",
"leadership_rotation": true,
"knowledge_sharing_score": 0.88,
"innovation_index": 0.76
},
"success_predictors": {
"completion_probability": 0.94,
"quality_forecast": 0.89,
"stakeholder_satisfaction_prediction": 0.87
}
}
```
### System-Wide Analytics
#### Get Platform Overview
```http
GET /api/v1/analytics/platform/overview
Authorization: Bearer {token}
Response 200:
{
"timestamp": "2025-09-08T15:00:00Z",
"system_status": "operational",
"global_metrics": {
"active_teams": 23,
"total_agents": 47,
"teams_formed_today": 3,
"teams_completed_today": 1,
"average_team_formation_time_minutes": 18.5,
"platform_uptime": 0.999
},
"agent_network": {
"online_agents": 44,
"busy_agents": 31,
"available_agents": 13,
"average_load": 0.67,
"network_health_score": 0.93
},
"team_formation_trends": {
"success_rate_7d": 0.91,
"average_team_size": 4.2,
"most_requested_roles": ["backend_developer", "security_architect", "qa_engineer"],
"formation_bottlenecks": ["security_architect", "ml_engineer"]
},
"quality_trends": {
"average_completion_quality": 0.87,
"consensus_achievement_rate": 0.92,
"artifact_reuse_rate": 0.34,
"continuous_improvement_score": 0.78
},
"resource_utilization": {
"compute_utilization": 0.68,
"storage_usage_gb": 847.3,
"network_bandwidth_utilization": 0.45,
"cost_efficiency_score": 0.82
}
}
```
## 📡 WebSocket Events
### Real-time Event Streaming
#### WebSocket Connection & Subscription
```javascript
// Connection
const ws = new WebSocket('wss://whoosh.chorus.services/ws');
// Authentication
ws.send(JSON.stringify({
type: 'authenticate',
token: 'bearer_jwt_token_here'
}));
// Subscribe to team events
ws.send(JSON.stringify({
type: 'subscribe',
topics: [
'team.team_auth_sys_001',
'agent.agent_security_gamma',
'platform.alerts'
]
}));
```
#### Event Types & Payloads
**Team Formation Events:**
```json
{
"type": "team.formation_started",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-03T12:30:00Z",
"data": {
"team_name": "Auth System Implementation Team",
"roles_needed": 5,
"estimated_formation_time_minutes": 15
}
}
{
"type": "team.agent_joined",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-03T13:15:00Z",
"data": {
"agent_id": "agent_security_gamma",
"role": "security_architect",
"team_size": 3,
"roles_remaining": 2
}
}
```
**Agent Activity Events:**
```json
{
"type": "agent.status_changed",
"agent_id": "agent_security_gamma",
"timestamp": "2025-09-05T09:10:00Z",
"data": {
"previous_status": "idle",
"current_status": "active",
"current_load": 0.65,
"team_assignments": ["team_auth_sys_001"]
}
}
{
"type": "agent.reasoning_shared",
"agent_id": "agent_security_gamma",
"timestamp": "2025-09-05T10:30:00Z",
"data": {
"reasoning_id": "reason_jwt_storage_001",
"team_id": "team_auth_sys_001",
"topic": "JWT Storage Strategy",
"feedback_requested": true
}
}
```
**Consensus & Decision Events:**
```json
{
"type": "team.vote_started",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-05T10:30:00Z",
"data": {
"vote_id": "vote_jwt_strategy_001",
"title": "JWT Storage Strategy Decision",
"eligible_voters": 4,
"deadline": "2025-09-05T18:30:00Z"
}
}
{
"type": "team.consensus_reached",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-05T16:15:00Z",
"data": {
"vote_id": "vote_jwt_strategy_001",
"winning_option": "option_memory_refresh",
"consensus_type": "supermajority",
"participation_rate": 1.0
}
}
```
This API specification provides the complete interface for WHOOSH's transformation into an Autonomous AI Development Teams platform, enabling sophisticated team orchestration, agent coordination, and collaborative development processes across the CHORUS ecosystem.
Reference in New Issue View Git Blame Copy Permalink