# Recipe Guide

Recipes are the core abstraction in neuraparse for transforming document graphs into datasets. Each recipe defines:

- **Input**: What nodes/edges from the graph to process
- **Processing logic**: How to transform graph data
- **Output schema**: The structure of the generated dataset

## Available Recipes

### 1. `rag_chunks`

**Purpose**: Generate paragraph chunks for RAG (Retrieval-Augmented Generation) systems.

**Output**: One record per paragraph node.

**Schema**:
```json
{
  "chunk_id": "str",
  "text": "str",
  "metadata": {
    "document_id": "str",
    "section_id": "str",
    "node_id": "str"
  }
}
```

**Example config**:
```json
{
  "kind": "rag_chunks",
  "name": "my_rag_chunks",
  "description": "Paragraph chunks for RAG"
}
```

**Use case**: Building vector databases for semantic search.

---

### 2. `basic_qa`

**Purpose**: Generate question-answer pairs from paragraphs using an LLM.

**Output**: One QA pair per paragraph.

**Schema**:
```json
{
  "question": "str",
  "answer": "str",
  "context": "str",
  "metadata": {...}
}
```

**Example config**:
```json
{
  "kind": "basic_qa",
  "params": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.7
    }
  }
}
```

**Use case**: Fine-tuning LLMs, creating QA datasets.

---

### 3. `outline_summary`

**Purpose**: Generate hierarchical section summaries.

**Output**: One record per section-level summary node.

**Schema**:
```json
{
  "section_title": "str",
  "summary": "str",
  "level": "int",
  "metadata": {...}
}
```

**Use case**: Document understanding, hierarchical retrieval.

---

### 4. `entity_knowledge`

**Purpose**: Aggregate entity mentions and contexts.

**Output**: One record per entity with all mentions.

**Schema**:
```json
{
  "entity": "str",
  "description": "str",
  "mentions": ["str", ...],
  "contexts": ["str", ...],
  "metadata": {...}
}
```

**Use case**: Knowledge graph construction, entity-centric retrieval.

---

### 5. `graph_neighborhood`

**Purpose**: Generate paragraph + neighborhood context (siblings, section summary).

**Output**: One record per paragraph with graph context.

**Schema**:
```json
{
  "paragraph": "str",
  "prev_sibling": "str | null",
  "next_sibling": "str | null",
  "section_summary": "str | null",
  "metadata": {...}
}
```

**Use case**: GraphRAG, context-aware retrieval.

---

### 6. `section_relevance`

**Purpose**: Generate binary relevance pairs for evaluation.

**Output**: (query, context, label) triples.

**Schema**:
```json
{
  "query_text": "str",
  "context_text": "str",
  "label": 0 | 1,
  "metadata": {...}
}
```

**Use case**: Training/evaluating binary relevance models.

---

### 7. `multi_context_ranking`

**Purpose**: Generate multi-context ranking datasets.

**Output**: One query with multiple contexts (positive/negative).

**Schema**:
```json
{
  "query_text": "str",
  "contexts": [
    {"context_text": "str", "label": 0 | 1},
    ...
  ],
  "metadata": {...}
}
```

**Use case**: Training ranking models, listwise learning.

---

### 8. `graded_relevance`

**Purpose**: Generate graded relevance pairs (0-3 labels).

**Output**: (query, context, grade) triples.

**Schema**:
```json
{
  "query_text": "str",
  "context_text": "str",
  "grade": 0 | 1 | 2 | 3,
  "metadata": {...}
}
```

**Grading logic**:
- **Grade 3** (highly relevant): Same section, adjacent paragraphs
- **Grade 2** (relevant): Same section, non-adjacent paragraphs
- **Grade 1** (marginally relevant): Different section, same document
- **Grade 0** (irrelevant): Distant sections

**Use case**: Training graded relevance models (NDCG, MAP).

---

### 9. `cross_document_ranking`

**Purpose**: Generate cross-document ranking datasets with explicit metadata.

**Output**: Multi-context ranking with source document tracking.

**Schema**:
```json
{
  "query_text": "str",
  "contexts": [
    {
      "context_text": "str",
      "label": 0 | 1,
      "source_document_id": "str",
      "relationship": "str"
    },
    ...
  ],
  "metadata": {...}
}
```

**Use case**: Multi-document retrieval, cross-doc negatives.

---

### 10. `entity_context_ranking`

**Purpose**: Generate ranking datasets mixing entity knowledge and section summaries.

**Output**: Multi-context ranking with entity + summary contexts.

**Schema**:
```json
{
  "query_text": "str",
  "contexts": [
    {
      "context_text": "str",
      "label": 0 | 1,
      "context_type": "entity" | "summary",
      "relationship": "str"
    },
    ...
  ],
  "metadata": {...}
}
```

**Use case**: Knowledge-enhanced retrieval, hybrid ranking.

---

## Creating Custom Recipes

To create a custom recipe:

1. Create a new file in `neuraparse/recipes/my_recipe.py`
2. Implement a `run_my_recipe` function:

```python
from pathlib import Path
from neuraparse.core.models import DatasetRecipe, DocumentGraph

def run_my_recipe(
    recipe: DatasetRecipe | None,
    graph: DocumentGraph,
    base_dir: str | Path,
    document_id: str,
) -> Path:
    # Your logic here
    pass
```

3. Register it in `neuraparse/recipes/__init__.py`
4. Add tests in `tests/test_my_recipe.py`

## Recipe Parameters

Recipes can accept parameters via the `params` field:

```json
{
  "kind": "my_recipe",
  "params": {
    "max_items": 100,
    "threshold": 0.5,
    "llm": {
      "provider": "openai",
      "model": "gpt-4"
    }
  }
}
```

Access params in your recipe:

```python
max_items = int((recipe.params or {}).get("max_items", 100))
```

## Next Steps

- [LLM Integration](llm_integration.md) - Use real LLMs in recipes
- [Profile System](profiles.md) - Bundle recipes into workflows
- [Examples](../examples/) - See real recipe configs

