80 lines
2.0 KiB
Markdown
80 lines
2.0 KiB
Markdown
|
---
|
||
|
|
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`)
|