---
name: Integration Guide
type: research
typical_query_count: 3-5
expected_output_length: 1000-2000 words
cascade_tier: groq_preferred
description: >
  Step-by-step guide to wire a specific tool into an existing stack,
  complete with code samples, configuration, and testing steps.
---

# Integration Guide: Wire {tool} into {stack}

## Context

Integrate **{tool}** into our **{stack}** stack. The goal is to
**{integration_goal}** (e.g., "add vector search to the dashboard",
"send notifications via Telegram").

## Constraints

- Must follow existing project conventions (see CLAUDE.md).
- No new cloud AI dependencies unless explicitly approved.
- Environment config via `pydantic-settings` / `config.py`.

## Research Steps

1. Review {tool}'s official documentation for installation and setup.
2. Identify the minimal dependency set required.
3. Map {tool}'s API to our existing patterns (singletons, graceful degradation).
4. Write integration code with proper error handling.
5. Define configuration variables and their defaults.

## Output Format

### Prerequisites

- Dependencies to install (with versions)
- External services or accounts required
- Environment variables to configure

### Configuration

```python
# In config.py — add these fields to Settings:
{config_fields}
```

### Implementation

```python
# {file_path}
{implementation_code}
```

### Graceful Degradation

Describe how the integration behaves when {tool} is unavailable:

| Scenario              | Behavior           | Log Level |
|-----------------------|--------------------|-----------|
| {tool} not installed  | {fallback}         | WARNING   |
| {tool} unreachable    | {fallback}         | WARNING   |
| Invalid credentials   | {fallback}         | ERROR     |

### Testing

```python
# tests/unit/test_{tool_snake}.py
{test_code}
```

### Verification Checklist

- [ ] Dependency added to pyproject.toml
- [ ] Config fields added with sensible defaults
- [ ] Graceful degradation tested (service down)
- [ ] Unit tests pass (`tox -e unit`)
- [ ] No new linting errors (`tox -e lint`)