fix: prevent cross-request contamination in CitationRegistry (#394)

[MestreY0d4-Uninter]

Description

This PR fixes a critical race condition bug in CitationRegistry where concurrent requests could corrupt citation IDs due to shared class-level state.

Problem

The original implementation used a class-level dictionary (_instances) shared across all requests. When two concurrent requests called init_citation_registry → assign_citation_ids_stateful, one request's reset() would wipe the global state while the other was mid-execution, causing:

• Corrupted or swapped citation IDs in responses
• Cross-session information leak (one user's citation state could be reset by another's request)

Solution

Replace class-level storage with thread-local storage using Python's threading.local(). This ensures:

• Each thread/request gets its own isolated registry instance
• No cross-request contamination
• Backward compatible with existing pipeline semantics

Changes

• servers/custom/src/custom.py: Refactor CitationRegistry and SurveyCPMCitationRegistry to use thread-local storage
• test_citation_registry_fix.py: Add test demonstrating thread isolation

Testing

Test passes with concurrent thread execution showing isolated state:

Thread 0: id1=1, id2=2, id3=1
Thread 1: id1=1, id2=2, id3=1
Thread 2: id1=1, id2=2, id3=1

Related Issue

Fixes #394

[MestreY0d4-Uninter]

Test Coverage

Added test_citation_registry_fix.py to verify thread isolation:

python3 test_citation_registry_fix.py

Results:

• ✅ All 5 concurrent threads got consistent, isolated results
• ✅ No cross-request contamination detected
• ✅ SurveyCPM registry also thread-safe

The fix uses Python's threading.local() to scope registry state per thread, preventing the race condition where concurrent reset() calls would wipe shared state.

[MestreY0d4-Uninter]

Evidencia Tecnica do Fix

Problema Original

O codigo original usava estado de classe compartilhado:

class CitationRegistry:
    _instances: Dict[int, Dict[str, Any]] = {}  # ❌ Compartilhado globalmente
    
    @classmethod
    def reset(cls):
        cls._instances = {}  # ❌ Limpa tudo para TODAS as threads

Solucao Implementada

Thread-local storage isola estado por thread de execucao:

_citation_registry_local = threading.local()

class CitationRegistry:
    @classmethod
    def reset(cls):
        if not hasattr(_citation_registry_local, '_instances'):
            _citation_registry_local._instances = {}
        else:
            _citation_registry_local._instances.clear()

Validacao

• ✅ Codigo compila e importa corretamente
• ✅ Pipeline sayhello.yaml builda com sucesso
• ✅ Testes de thread isolation passam (5 threads concorrentes)
• ✅ Backward compatible com pipelines existentes

Impacto

• Scope: servers/custom/src/custom.py
• Classes afetadas: CitationRegistry, SurveyCPMCitationRegistry
• Breaking changes: Nenhum (API unchanged)
• Performance: Neutro (thread-local é O(1))

[MestreY0d4-Uninter]

Melhorias no Hub de Contribuição (Global)

Além do fix da issue #394, este PR também inclui melhorias globais no hub de contribuição:

Problemas Corrigidos

1. ✅ CONTRIBUTING.md estava incompleto (tinha 'TODO' no setup)
2. ✅ Sem suite de testes formal no repositório
3. ✅ Sem validação automatizada para contribuidores

Soluções Implementadas

• CONTRIBUTING.md: Preenchido com instruções completas de setup
• tests/: Diretório criado com README e template
• pyproject.toml: Config do pytest adicionada
• scripts/validate_contribution.py: Validação automática do ambiente
• docs/CONTRIBUTING_IMPROVEMENTS.md: Documentação das melhorias

Impacto

• ✅ Novos contribuidores conseguem setupar o ambiente facilmente
• ✅ Template de teste padronizado para contribuições
• ✅ Script de validação para verificar setup antes de contribuir
• ✅ Reutilizável para todas as futuras contribuições

Estas melhorias são globais e beneficiam todo o ecossistema UltraRAG, não apenas o fix específico da #394.

[MestreY0d4-Uninter]

Update

Squashed to single commit with only the fix for issue #394.

Changes:

• : Thread-local storage for CitationRegistry
• : Test validating the fix

All other changes were unrelated to this PR and have been removed.