Source: data_layer/docs/CONSOLIDATION_PLAN_REVISED.md

Examples Consolidation Plan (REVISED)

🎯 Goal

Move few-shot examples infrastructure to proper service location (apps/backend/services/) and consolidate all example data under database/output-styles/examples/.

📋 Revised Architecture

✅ Data Layer: `database/output-styles/examples/`

database/output-styles/examples/
├── README.md                          # Master documentation
├── examples_index.json                # Master index (existing)
├── validation-framework.json          # Validation rules (existing)
│
├── by-scenario/                       # Structured JSON (existing)
│   ├── triage.json
│   ├── response-generation.json
│   ├── pdf-processing.json
│   ├── contract-generation.json
│   ├── onboarding.json
│   └── workflow-chain.json
│
├── edge-cases/                        # Edge case examples (existing)
│   └── edge-cases.json
│
├── seeds/                             # 🆕 JSONL files for DB seeding
│   ├── README.md
│   ├── triage.jsonl
│   ├── contract-generation.jsonl
│   ├── pdf-processing.jsonl
│   ├── response-generation.jsonl
│   ├── onboarding-response.jsonl
│   ├── league_examples.jsonl
│   ├── questionnaires.jsonl
│   └── schema_definitions.jsonl
│
└── embeddings/                        # 🆕 Vector embeddings
    ├── README.md
    ├── triage_embeddings.npy
    ├── contract_embeddings.npy
    └── metadata.json

✅ Service Layer: `apps/backend/services/few_shot_examples/`

apps/backend/services/few_shot_examples/
├── __init__.py                        # Service exports
├── README.md                          # Service documentation
│
├── api.py                             # High-level API interface
├── retriever.py                       # Core retrieval logic
├── matcher.py                         # Semantic similarity matching
├── cache.py                           # LRU caching system
├── example_manager.py                 # JSONL utilities
│
├── config.py                          # Configuration (paths, settings)
├── models.py                          # Pydantic models
│
└── tests/
    ├── test_api.py
    ├── test_retriever.py
    ├── test_matcher.py
    └── test_cache.py

🔄 Migration Steps

Phase 1: Create Service Structure ✅

# Create service directory
mkdir -p apps/backend/services/few_shot_examples/tests
 
# Create __init__.py files
touch apps/backend/services/few_shot_examples/__init__.py
touch apps/backend/services/few_shot_examples/tests/__init__.py

Phase 2: Move Infrastructure Code ✅

# Move Python modules
mv database/few_shot_examples_training_data/api.py \
   apps/backend/services/few_shot_examples/
 
mv database/few_shot_examples_training_data/retriever.py \
   apps/backend/services/few_shot_examples/
 
mv database/few_shot_examples_training_data/matcher.py \
   apps/backend/services/few_shot_examples/
 
mv database/few_shot_examples_training_data/cache.py \
   apps/backend/services/few_shot_examples/
 
mv database/few_shot_examples_training_data/example_manager.py \
   apps/backend/services/few_shot_examples/
 
# Move tests if they exist
if [ -f database/few_shot_examples_training_data/test_*.py ]; then
    mv database/few_shot_examples_training_data/test_*.py \
       apps/backend/services/few_shot_examples/tests/
fi

Phase 3: Create Data Structure ✅

# Create seeds and embeddings directories
mkdir -p database/output-styles/examples/seeds
mkdir -p database/output-styles/examples/embeddings
 
# Move JSONL files
mv database/few_shot_examples_training_data/data/*.jsonl \
   database/output-styles/examples/seeds/
 
# Move subdirectories if needed
if [ -d database/few_shot_examples_training_data/data/contract_sections ]; then
    mv database/few_shot_examples_training_data/data/contract_sections \
       database/output-styles/examples/seeds/
fi

Phase 4: Create Configuration ✅

# Create config.py in service
cat > apps/backend/services/few_shot_examples/config.py << 'EOF'
"""Configuration for Few-Shot Examples Service."""
from pathlib import Path
from typing import Optional
from pydantic_settings import BaseSettings
 
 
class FewShotConfig(BaseSettings):
    """Configuration for Few-Shot Examples Service."""
    
    # Data paths (relative to project root)
    EXAMPLES_ROOT: Path = Path("database/output-styles/examples")
    SEEDS_DIR: Path = EXAMPLES_ROOT / "seeds"
    STRUCTURED_DIR: Path = EXAMPLES_ROOT / "by-scenario"
    EDGE_CASES_DIR: Path = EXAMPLES_ROOT / "edge-cases"
    EMBEDDINGS_DIR: Path = EXAMPLES_ROOT / "embeddings"
    
    # Cache configuration
    CACHE_MAX_SIZE: int = 2000
    CACHE_TTL_SECONDS: int = 7200  # 2 hours
    
    # Retrieval configuration
    DEFAULT_MAX_EXAMPLES: int = 5
    DEFAULT_QUALITY_THRESHOLD: float = 0.80
    
    # Database configuration
    DATABASE_URL: Optional[str] = None
    
    class Config:
        env_prefix = "FEW_SHOT_"
        case_sensitive = False
 
 
# Global config instance
config = FewShotConfig()
EOF

Phase 5: Update Service Code ✅

# Update imports in each file
 
# In api.py:
from apps.backend.services.few_shot_examples.config import config
from apps.backend.services.few_shot_examples.retriever import FewShotRetriever
from apps.backend.services.few_shot_examples.cache import ExampleCache
 
# In retriever.py:
from apps.backend.services.few_shot_examples.config import config
from apps.backend.services.few_shot_examples.matcher import SemanticMatcher
from apps.backend.services.few_shot_examples.cache import ExampleCache
 
# In example_manager.py:
from apps.backend.services.few_shot_examples.config import config
 
# Update DEFAULT_DATA_DIR:
DEFAULT_DATA_DIR = config.SEEDS_DIR

Phase 6: Update Service init.py ✅

# apps/backend/services/few_shot_examples/__init__.py
"""Few-Shot Examples Service.
 
Provides intelligent retrieval of few-shot examples for prompt engineering.
 
Usage:
    from apps.backend.services.few_shot_examples import FewShotExamplesAPI
    
    api = FewShotExamplesAPI()
    examples = await api.get_examples_for_prompt(
        prompt_text="partnership inquiry",
        prompt_type="triage",
        max_examples=5
    )
"""
 
from .api import FewShotExamplesAPI
from .retriever import FewShotRetriever, RetrievalContext, RetrievalStrategy
from .matcher import SemanticMatcher
from .cache import ExampleCache
from .example_manager import ExampleManager
from .config import config, FewShotConfig
 
__all__ = [
    "FewShotExamplesAPI",
    "FewShotRetriever",
    "RetrievalContext",
    "RetrievalStrategy",
    "SemanticMatcher",
    "ExampleCache",
    "ExampleManager",
    "config",
    "FewShotConfig",
]

Phase 7: Update Scripts ✅

# In scripts/seed.examples.py
from apps.backend.services.few_shot_examples import ExampleManager, config
 
# Update paths
JSONL_DIR = config.SEEDS_DIR

Phase 8: Update Existing Imports ✅

# Find all files that import from old location
grep -r "from database.few_shot_examples_training_data" apps/backend/
 
# Update each import:
# OLD:
from database.few_shot_examples_training_data import FewShotExamplesAPI
 
# NEW:
from apps.backend.services.few_shot_examples import FewShotExamplesAPI

Phase 9: Clean Up Old Structure ✅

# Remove old directory (after verifying migration)
rm -rf database/few_shot_examples_training_data/
 
# Update .gitignore if needed
echo "database/output-styles/examples/embeddings/*.npy" >> .gitignore

📝 Create Documentation

Service README

# Few-Shot Examples Service
 
## Location
`apps/backend/services/few_shot_examples/`
 
## Purpose
Provides intelligent retrieval of few-shot examples for prompt engineering across the AltSports Data platform.
 
## Architecture
 
### Service Layer (this directory)
- **API**: High-level interface for example retrieval
- **Retriever**: Core retrieval logic with multiple strategies
- **Matcher**: Semantic similarity matching
- **Cache**: LRU caching for performance
- **Example Manager**: JSONL file utilities
 
### Data Layer (`database/output-styles/examples/`)
- **seeds/**: JSONL files for database seeding
- **by-scenario/**: Structured JSON examples
- **edge-cases/**: Edge case handling
- **embeddings/**: Vector embeddings
 
## Usage
 
```python
from apps.backend.services.few_shot_examples import FewShotExamplesAPI
 
api = FewShotExamplesAPI()
 
# Get examples for a prompt
examples = await api.get_examples_for_prompt(
    prompt_text="partnership inquiry from premium soccer league",
    prompt_type="triage",
    business_tier="premium",
    sport_type="soccer",
    max_examples=3
)
 
# Direct Prisma query
from prisma import Prisma
 
db = Prisma()
await db.connect()
 
examples = await db.fewshotexample.find_many(
    where={"category": "triage", "tier": "premium"},
    order_by={"quality_score": "desc"},
    take=5
)

Configuration

Set via environment variables:

FEW_SHOT_CACHE_MAX_SIZE=2000
FEW_SHOT_CACHE_TTL_SECONDS=7200
FEW_SHOT_DEFAULT_MAX_EXAMPLES=5

Or via code:

from apps.backend.services.few_shot_examples import config
 
config.CACHE_MAX_SIZE = 3000

Data Management

Seed Database

uv run python scripts/seed.examples.py --category triage

Add Examples

Edit JSONL file in database/output-styles/examples/seeds/
Run seed script
Verify via API or Prisma

Testing

# Run service tests
pytest apps/backend/services/few_shot_examples/tests/
 
# Test API
python -c "from apps.backend.services.few_shot_examples import FewShotExamplesAPI; print('✅ Service import works')"


### Data README
```markdown
# Few-Shot Examples Data

## Location
`database/output-styles/examples/`

## Structure

- **by-scenario/**: Human-readable reference examples (JSON)
- **edge-cases/**: Edge case handling examples (JSON)
- **seeds/**: Database seed files (JSONL)
- **embeddings/**: Vector embeddings for semantic search (NPY)

## Retrieval Methods

### 1. Direct JSON Reading
Fast file reading for documentation and reference:
```python
import json
from pathlib import Path

examples = json.load(
    Path("database/output-styles/examples/by-scenario/triage.json").open()
)

2. Database Queries

Fast indexed queries via Prisma:

from apps.backend.services.few_shot_examples import FewShotExamplesAPI
 
api = FewShotExamplesAPI()
examples = await api.get_examples_for_prompt(
    prompt_text="partnership inquiry",
    prompt_type="triage"
)

3. Semantic Search (Future)

Vector embedding similarity:

from apps.backend.services.few_shot_examples import SemanticMatcher
 
matcher = SemanticMatcher()
similar = await matcher.find_similar(
    "partnership inquiry from premium league",
    top_k=5
)

Maintenance

Add Examples: Edit JSONL in seeds/, run seed script
Update Examples: Edit JSONL, reseed (upserts existing)
Quality Review: Quarterly review of examples


## 🎯 Benefits of Revised Architecture

### ✅ Clean Separation

Database Layer: database/output-styles/examples/ # Data only Service Layer: apps/backend/services/few_shot_examples/ # Logic only


### ✅ Proper Service Architecture
- Aligns with `apps/backend/services/` pattern
- Clear service boundaries and responsibilities
- Easy to test, mock, and maintain

### ✅ Consistent with Backend Structure

apps/backend/ ├── agents/ # Agent implementations ├── api/ # API endpoints ├── services/ # Business logic services │ ├── few_shot_examples/ # ← Our service here │ ├── league_processing/ │ └── contract_generation/ └── routers/ # Route handlers


### ✅ Import Clarity
```python
# Clear, semantic imports
from apps.backend.services.few_shot_examples import FewShotExamplesAPI
from apps.backend.services.contract_generation import ContractGenerator
from apps.backend.services.league_processing import LeagueProcessor

📊 Migration Comparison

Aspect	Before	After
Service Location	`database/few_shot_examples_training_data/`	`apps/backend/services/few_shot_examples/`
Data Location	`database/few_shot_examples_training_data/data/`	`database/output-styles/examples/seeds/`
Architecture	Mixed data + logic	Clean separation
Consistency	Inconsistent with project	Follows service pattern
Imports	Long, unclear	Short, semantic

✅ Validation Checklist

🚀 Quick Migration Command

#!/bin/bash
# migrate-few-shot-service.sh
 
set -e
 
echo "🚀 Migrating Few-Shot Examples to proper service location..."
 
# 1. Create service structure
mkdir -p apps/backend/services/few_shot_examples/tests
 
# 2. Move infrastructure
mv database/few_shot_examples_training_data/*.py \
   apps/backend/services/few_shot_examples/ 2>/dev/null || true
 
# 3. Create data structure
mkdir -p database/output-styles/examples/seeds
mkdir -p database/output-styles/examples/embeddings
 
# 4. Move data
mv database/few_shot_examples_training_data/data/*.jsonl \
   database/output-styles/examples/seeds/ 2>/dev/null || true
 
# 5. Create config
cat > apps/backend/services/few_shot_examples/config.py << 'EOF'
# Config content here...
EOF
 
# 6. Update imports
echo "⚠️  Manual step: Update imports in your code"
echo "   OLD: from database.few_shot_examples_training_data import ..."
echo "   NEW: from apps.backend.services.few_shot_examples import ..."
 
# 7. Clean up
echo "🧹 After verifying migration, remove old directory:"
echo "   rm -rf database/few_shot_examples_training_data/"
 
echo "✅ Migration structure created!"
echo "📝 Next: Update imports and test"

🎓 Summary

Architecture Change:

❌ database/few_shot_examples_training_data/  (mixed data + logic)
✅ apps/backend/services/few_shot_examples/   (service logic)
✅ database/output-styles/examples/           (data only)

Key Improvements:

✅ Proper service architecture
✅ Clean data/logic separation
✅ Consistent with project patterns
✅ Better imports and discoverability
✅ Easier to test and maintain

Examples Consolidation Plan Executive Summary: Prompt Management System

Examples Consolidation Plan (REVISED)

🎯 Goal

📋 Revised Architecture

✅ Data Layer: `database/output-styles/examples/`

✅ Service Layer: `apps/backend/services/few_shot_examples/`

🔄 Migration Steps

Phase 1: Create Service Structure ✅

Phase 2: Move Infrastructure Code ✅

Phase 3: Create Data Structure ✅

Phase 4: Create Configuration ✅

Phase 5: Update Service Code ✅

Phase 6: Update Service init.py ✅

Phase 7: Update Scripts ✅

Phase 8: Update Existing Imports ✅

Phase 9: Clean Up Old Structure ✅

📝 Create Documentation

Service README

Configuration

Data Management

Seed Database

Add Examples

Testing

2. Database Queries

3. Semantic Search (Future)

Maintenance

📊 Migration Comparison

✅ Validation Checklist

🚀 Quick Migration Command

🎓 Summary

Platform

Documentation

Community

Support

Examples Consolidation Plan (REVISED)

🎯 Goal

📋 Revised Architecture

✅ Data Layer: database/output-styles/examples/

✅ Service Layer: apps/backend/services/few_shot_examples/

🔄 Migration Steps

Phase 1: Create Service Structure ✅

Phase 2: Move Infrastructure Code ✅

Phase 3: Create Data Structure ✅

Phase 4: Create Configuration ✅

Phase 5: Update Service Code ✅

Phase 6: Update Service init.py ✅

Phase 7: Update Scripts ✅

Phase 8: Update Existing Imports ✅

Phase 9: Clean Up Old Structure ✅

📝 Create Documentation

Service README

Configuration

Data Management

Seed Database

Add Examples

Testing

2. Database Queries

3. Semantic Search (Future)

Maintenance

📊 Migration Comparison

✅ Validation Checklist

🚀 Quick Migration Command

🎓 Summary

Platform

Documentation

Community

Support

✅ Data Layer: `database/output-styles/examples/`

✅ Service Layer: `apps/backend/services/few_shot_examples/`