# Tipos: Retrieval (TypedQuery, MatchedContext, QueryResult, FindResult)

Fuente conceptual: OpenViking `openviking_cli/retrieve/types.py` (AGPL-3.0)
Reimplementar desde cero. No copiar codigo.

## Tipos a implementar

### 1. ContextType (enum/sum)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** sum
- **Definicion:**
  ```python
  class ContextType(str, Enum):
      MEMORY = "memory"
      RESOURCE = "resource"
      SKILL = "skill"
  ```
- **Descripcion:** Tipo de contexto para busqueda/retrieval. Permite filtrar resultados por categoria.

### 2. TypedQuery (product)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class TypedQuery:
      query: str                                  # texto de la query
      context_type: ContextType | None            # tipo de contexto objetivo
      intent: str                                 # descripcion de la intencion
      priority: int = 3                           # 1-5 (1 es mayor prioridad)
      target_directories: list[str] = field(default_factory=list)  # URIs de directorios objetivo
  ```
- **Descripcion:** Query tipada que resulta del analisis de intenciones. Un plan de busqueda se descompone en multiples TypedQueries, cada una apuntando a un tipo de contexto diferente.

### 3. QueryPlan (product)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class QueryPlan:
      queries: list[TypedQuery]
      session_context: str                        # resumen del contexto de sesion
      reasoning: str                              # razonamiento del LLM
  ```
- **Descripcion:** Plan de busqueda generado por analisis de intenciones (LLM). Contiene multiples queries tipadas y el razonamiento detras de la descomposicion.

### 4. RelatedContext (product)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class RelatedContext:
      uri: str
      abstract: str
  ```

### 5. MatchedContext (product)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class MatchedContext:
      uri: str
      context_type: ContextType
      level: int = 2                              # 0=abstract, 1=overview, 2=detail
      abstract: str = ""
      overview: str | None = None
      category: str = ""
      score: float = 0.0                          # 0-1 relevancia
      match_reason: str = ""
      relations: list[RelatedContext] = field(default_factory=list)
  ```
- **Descripcion:** Contexto encontrado por el retriever con su score de relevancia, nivel de detalle, y contextos relacionados.

### 6. ScoreDistribution (product)

- **Dominio:** datascience
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class ScoreDistribution:
      scores: list[tuple[str, float]]             # [(uri, score), ...] ordenados desc
      min_score: float = 0.0
      max_score: float = 0.0
      mean_score: float = 0.0
      threshold: float = 0.0
  ```
- **Metodos:**
  - `from_scores(uri_scores, threshold=0.0) -> ScoreDistribution` (classmethod) — calcula stats
  - `to_dict() -> dict` — incluye count y above_threshold
- **Descripcion:** Estadisticas de distribucion de scores para visualizacion y debugging de retrieval.

### 7. QueryResult (product)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class QueryResult:
      query: TypedQuery
      matched_contexts: list[MatchedContext]
      searched_directories: list[str]
  ```
- **Descripcion:** Resultado de una sola TypedQuery con los contextos encontrados y los directorios que se buscaron.

### 8. FindResult (product)

- **Dominio:** core
- **Lang:** Python
- **Algebraic:** product
- **Definicion:**
  ```python
  @dataclass
  class FindResult:
      memories: list[MatchedContext]
      resources: list[MatchedContext]
      skills: list[MatchedContext]
      query_plan: QueryPlan | None = None
      query_results: list[QueryResult] | None = None
      total: int = 0                              # auto-calculado en __post_init__
  ```
- **Metodos:**
  - `__iter__` — itera sobre todos los MatchedContext (memories + resources + skills)
  - `__post_init__` — calcula total
  - `to_dict(include_provenance=False) -> dict` — serializacion
  - `from_dict(data: dict) -> FindResult` (classmethod) — deserializacion
- **Descripcion:** Resultado final de una busqueda completa, agrupado por tipo de contexto. Opcionalmente incluye provenance (traza de busqueda) para observabilidad.
