feat: add CLARITY subagent for Clarity Protocol integration

[clarityprotocol]

Summary

• Adds a third task type (CLARITY) to BioAgents deep research, enabling BIOS to query Clarity Protocol for protein fold predictions, clinical annotations, and AI agent findings when researching disease-linked protein variants
• New agent at src/agents/clarity/ with API client, variant parser, and orchestrator
• Integrated into planning prompts, deep research execution (both in-process and queue modes), and clarification agent
• 12 files changed, 754 insertions

What it does

When BIOS researches a protein variant (e.g., SOD1 A4V, tau P301L), the planning agent can now generate CLARITY tasks alongside LITERATURE and ANALYSIS tasks. The clarity agent:

1. Parses protein name + variant from the research objective
2. Searches Clarity Protocol for matching fold data
3. Fetches variant detail (pLDDT scores, AI summary, research brief)
4. Fetches agent findings and annotations from Clarity's 4 research agents
5. Fetches clinical data (ClinVar + gnomAD)
6. Returns structured markdown output for the research pipeline

Config

CLARITY_API_URL=https://clarityprotocol.io/api/v1
CLARITY_API_KEY=  # Optional, for higher rate limits

Test plan

• Run deep research with a protein variant query (e.g., 'What is known about SOD1 A4V?')
• Verify CLARITY tasks appear in planning output
• Verify clarity agent returns fold data, findings, and clinical data
• Verify graceful fallback when variant not found in Clarity

[greptile-apps]

Greptile Summary

Added CLARITY as a third task type to BioAgents deep research, enabling queries to Clarity Protocol for protein fold predictions, clinical annotations, and AI agent findings for disease-linked variants.

Key Changes:

• New agent at src/agents/clarity/ with API client, variant parser, and orchestrator
• Integrated into planning prompts (all three planning scenarios), deep-research execution (both in-process and queue modes), and clarification agent
• Parallel API fetching for variant details, findings, annotations, and clinical data with individual error handlers
• Graceful fallback when variants not found or API calls fail
• Follows existing patterns for external service integration with proper error handling and logging
• Configuration added for optional API key to support higher rate limits

Implementation Quality:

• Follows CLAUDE.md guidelines for external service integration with graceful error handling
• No Temporal Dead Zone (TDZ) issues - all process.env access is inside functions
• Consistent error handling pattern across both in-process and worker modes
• Proper URL encoding for user inputs (protein names, variants)
• Uses fetchWithRetry utility with exponential backoff
• Parser handles common edge cases with skipWords list

Confidence Score: 4/5

• This PR is safe to merge after manual testing
• Well-structured implementation following established patterns with comprehensive error handling. Score is 4 (not 5) because: (1) test plan checklist is unchecked suggesting manual testing incomplete, (2) parser limited to single amino acid substitutions which may not cover all use cases, (3) flexible API response parsing could mask future API contract changes. No critical bugs or security issues found.
• Verify src/agents/clarity/parser.ts handles all expected variant notation formats in production queries

Important Files Changed

Filename	Overview
src/agents/clarity/parser.ts	Regex-based parser for extracting protein name and variant from objectives; handles single amino acid substitutions
src/agents/clarity/api.ts	API client for Clarity Protocol with retry logic; uses flexible response parsing that could mask API changes
src/agents/clarity/index.ts	Main orchestrator that parses variants, queries Clarity API, and formats structured markdown output with graceful error handling
src/agents/planning/prompts.ts	Added CLARITY task type with descriptions and formatting guidelines across all planning prompts
src/routes/deep-research/start.ts	Integrated CLARITY task execution with error handling and state updates
src/services/queue/workers/deep-research.worker.ts	Added CLARITY task handling in worker process with consistent error handling

Sequence Diagram

sequenceDiagram
    participant User
    participant Planning
    participant DeepResearch
    participant ClarityAgent
    participant ClarityAPI
    
    User->>Planning: Research protein variant (e.g., "SOD1 A4V")
    Planning->>Planning: Generate CLARITY task
    Planning->>DeepResearch: Execute CLARITY task
    DeepResearch->>ClarityAgent: clarityAgent({objective})
    
    ClarityAgent->>ClarityAgent: parseVariantFromObjective()
    Note over ClarityAgent: Extract protein name & variant<br/>(e.g., "SOD1" + "A4V")
    
    ClarityAgent->>ClarityAPI: searchVariants(protein)
    ClarityAPI-->>ClarityAgent: variants[]
    ClarityAgent->>ClarityAgent: Match variant by name
    
    par Parallel API Calls
        ClarityAgent->>ClarityAPI: getVariantDetail(foldId)
        ClarityAPI-->>ClarityAgent: detail (pLDDT scores, AI summary)
        ClarityAgent->>ClarityAPI: getFindings(foldId)
        ClarityAPI-->>ClarityAgent: findings[] (agent research)
        ClarityAgent->>ClarityAPI: getAnnotations(foldId)
        ClarityAPI-->>ClarityAgent: annotations[]
        ClarityAgent->>ClarityAPI: getClinicalData(gene, variant)
        ClarityAPI-->>ClarityAgent: clinical (ClinVar, gnomAD)
    end
    
    ClarityAgent->>ClarityAgent: formatClarityOutput()
    Note over ClarityAgent: Build structured markdown<br/>with all data sections
    ClarityAgent-->>DeepResearch: {output, reasoning}
    DeepResearch-->>User: Formatted Clarity Protocol data

Loading

_{Last reviewed commit: 46ce6e1}