Sangeetha-Grantha

Metadata	Value
Status	Active
Version	1.1.0
Last Updated	2026-09-10
Author	Sangeetha Grantha Team
Document Type	Design reference

Koog Framework Evaluation for Import Pipeline

[!NOTE] Design/reference material: this page may include proposals or earlier implementation assumptions. Use current ingestion guide for implemented behavior and current operating steps.

Document Consolidation Note

This document consolidates Koog evaluation from multiple sources:

Primary Source: koog-evaluation-for-import-pipeline-goose.md (Import pipeline specific evaluation)
Supplemental Sources:
- koog-integration-analysis.md (General integration options)
- koog-technical-integration-proposal.md (Technical integration details)

Key insights from all sources have been integrated into this consolidated evaluation.

1. Executive Summary

This document provides a detailed evaluation of Koog specifically for the Krithi import pipeline use case. It builds on existing Koog analysis documents and provides import-pipeline-specific recommendations.

Key Finding: Koog offers significant value for complex, multi-stage import workflows, but may be over-engineered for initial phases. A phased evaluation approach is recommended: start with custom workflow, then evaluate Koog for specific pain points.

2. Import Pipeline Requirements Recap

2.1 Pipeline Stages

The import pipeline consists of 10 stages:

Discovery - URL collection
Scraping - HTML fetching
Extraction - AI-powered content extraction
Entity Resolution - Map to canonical entities
Data Cleansing - Normalization
De-duplication - Duplicate detection
Validation - Quality checks
Staging - Store in imported_krithis
Human Moderation - Review workflow
Canonicalization - Create Krithi entities

2.2 Key Requirements

Multi-stage orchestration: Sequential and parallel stages
Error handling: Retry logic, failure recovery
Observability: Track progress, debug failures
Scalability: Handle 1000+ URLs per batch
Flexibility: Support multiple source types
Quality: Human-in-the-loop validation

3. Koog Capabilities for Import Pipeline

3.1 Graph Workflows

Koog Strength: Define complex workflows as graphs

Import Pipeline as Koog Graph:

val importWorkflow = agent {
    graph {
        val discovery = node("discover") { discoverUrls(source) }
        val scraping = node("scrape") { scrapeUrl(url) }
        val extraction = node("extract") { extractMetadata(html) }
        val entityResolution = node("resolve") { resolveEntities(metadata) }
        val cleansing = node("cleanse") { cleanseData(mapped) }
        val deduplication = node("dedupe") { findDuplicates(cleaned) }
        val validation = node("validate") { validateData(processed) }
        val staging = node("stage") { stageForReview(validated) }
        
        discovery -> scraping -> extraction -> entityResolution -> 
        cleansing -> deduplication -> validation -> staging
    }
}

Benefits:

✅ Visual workflow representation
✅ Easy to add/remove stages
✅ Parallel execution where possible
✅ Conditional branching (e.g., skip validation if low confidence)

Considerations:

Learning curve for team
Overhead for simple linear workflows
Debugging graph execution

3.2 Tool Calling

Koog Strength: Integrate external systems as tools

Import Pipeline Tools:

val scrapingTool = tool("scrape_url") {
    description = "Scrape HTML content from URL"
    parameter<String>("url")
    execute { url ->
        webScrapingService.scrape(url)
    }
}

val entityResolutionTool = tool("resolve_composer") {
    description = "Resolve composer name to canonical entity"
    parameter<String>("name")
    execute { name ->
        entityResolutionService.resolveComposer(name)
    }
}

val validationTool = tool("validate_krithi") {
    description = "Validate extracted Krithi data"
    parameter<ExtractedMetadata>("metadata")
    execute { metadata ->
        validationService.validate(metadata)
    }
}

Benefits:

✅ Type-safe tool definitions
✅ LLM can call tools intelligently
✅ Reusable across workflows
✅ Easy to test in isolation

Considerations:

Tool definition overhead
LLM tool calling adds latency
May be overkill for deterministic operations

3.3 Retry & Fault Tolerance

Koog Strength: Built-in retry and persistence

Retry Configuration:

agent {
    retryPolicy {
        maxRetries = 3
        backoffStrategy = ExponentialBackoff(
            initialDelay = 1.seconds,
            maxDelay = 30.seconds
        )
    }
    
    persistence {
        // Save workflow state for recovery
        storage = DatabasePersistence(db)
    }
}

Benefits:

✅ Automatic retry on failures
✅ State persistence for long-running workflows
✅ Resume from failure point
✅ Configurable retry strategies

Considerations:

Persistence adds complexity
State management overhead
May not be needed for short workflows

3.4 Observability

Koog Strength: OpenTelemetry integration

**Tracing:**

agent { tracing { exporter = OpenTelemetryExporter() level = TraceLevel.DETAILED } }

**Benefits:**
- ✅ Comprehensive tracing
- ✅ Integration with monitoring tools
- ✅ Performance insights
- ✅ Debug workflow execution

**Considerations:**
- Setup overhead
- May be overkill initially
- Can add later if needed

---

### 3.5 Provider Flexibility

**Koog Strength**: Switch LLM providers easily

Multi-Provider Support:

agent {
    llm = when (stage) {
        "extraction" -> GeminiProvider(model = "gemini-2.0-flash-exp")
        "validation" -> GeminiProvider(model = "gemini-1.5-pro")
        else -> GeminiProvider(model = "gemini-2.0-flash-exp")
    }
}

Benefits:

✅ Use different models for different stages
✅ Cost optimization (Flash for simple, Pro for complex)
✅ Fallback providers
✅ Easy experimentation

Considerations:

Current Gemini integration works fine
Provider switching may not be needed
Adds abstraction layer

4. Koog vs. Custom Workflow Comparison

4.1 Feature Comparison Matrix

Feature	Koog	Custom (Coroutines)	Winner
Workflow Definition	Graph DSL	Function composition	Koog (more expressive)
Error Handling	Built-in retry	Manual implementation	Koog (less code)
Observability	OpenTelemetry	Manual logging	Koog (better)
State Persistence	Built-in	Manual (DB)	Koog (easier)
Learning Curve	Medium-High	Low	Custom (team knows it)
Performance	Some overhead	Direct execution	Custom (faster)
Flexibility	Framework constraints	Full control	Custom (more flexible)
Maintenance	Framework updates	Own code	Custom (more control)
Provider Switching	Easy	Manual	Koog (if needed)
Tool Calling	Built-in	Manual	Koog (if using LLM tools)

4.2 Code Complexity Comparison

suspend fun importPipeline(url: String): ImportResult {
    return try {
        val html = webScrapingService.scrape(url)
        val extracted = extractionService.extract(html)
        val resolved = entityResolutionService.resolve(extracted)
        val cleaned = cleansingService.cleanse(resolved)
        val validated = validationService.validate(cleaned)
        stagingService.stage(validated)
        ImportResult.Success
    } catch (e: Exception) {
        // Manual retry logic
        if (retryCount < 3) {
            delay(exponentialBackoff(retryCount))
            importPipeline(url)
        } else {
            ImportResult.Failure(e)
        }
    }
}

Koog Workflow:

val importAgent = agent {
    graph {
        val scrape = node("scrape") { scrapeUrl(url) }
        val extract = node("extract") { extractMetadata(html) }
        val resolve = node("resolve") { resolveEntities(metadata) }
        val cleanse = node("cleanse") { cleanseData(mapped) }
        val validate = node("validate") { validateData(cleaned) }
        val stage = node("stage") { stageForReview(validated) }
        
        scrape -> extract -> resolve -> cleanse -> validate -> stage
    }
    
    retryPolicy { maxRetries = 3 }
    tracing { level = TraceLevel.DETAILED }
}

Analysis:

Custom: ~20 lines, straightforward, team understands it
Koog: ~15 lines, more declarative, requires framework knowledge
Winner: Depends on team preference and future needs

5. Use Case Analysis

5.1 Where Koog Excels

Complex, Multi-Stage Workflows:

✅ 10-stage pipeline benefits from graph representation
✅ Conditional branching (e.g., skip validation if high confidence)
✅ Parallel execution (e.g., resolve composer + raga + deity in parallel)

Long-Running Workflows:

✅ State persistence for batch processing
✅ Resume from failure point
✅ Progress tracking

LLM-Heavy Workflows:

✅ Tool calling for AI operations
✅ Provider flexibility
✅ Intelligent retry for LLM failures

Observability Requirements:

✅ Comprehensive tracing
✅ Integration with monitoring
✅ Performance insights

5.2 Where Custom Solution Excels

Simple, Linear Workflows:

✅ Less overhead
✅ Easier to debug
✅ Team familiarity

Performance-Critical Paths:

✅ Direct execution
✅ No framework overhead
✅ Fine-grained control

Rapid Iteration:

✅ Quick changes
✅ No framework constraints
✅ Direct testing

Existing Infrastructure:

✅ Leverage existing services
✅ No new dependencies
✅ Consistent patterns

6. Hybrid Approach Recommendation

6.1 Phase 1: Custom Workflow (Weeks 1-4)

Build custom coroutine-based pipeline:

Leverage existing WebScrapingService
Build EntityResolutionService
Create ImportPipelineService with coroutines
Basic retry and error handling
Simple logging

Rationale:

Fast to implement
Team understands it
Meets immediate needs
Low risk

6.2 Phase 2: Koog POC (Weeks 5-6)

Build Koog POC for one stage:

Choose most complex stage (likely extraction or entity resolution)
Implement same functionality with Koog
Compare performance, maintainability, observability
Document findings

POC Criteria:

Performance: Latency, throughput
Maintainability: Code clarity, ease of changes
Observability: Tracing, debugging
Error Handling: Retry effectiveness
Team Feedback: Learning curve, developer experience

6.3 Phase 3: Decision Point

If Koog Adds Value:

Adopt for complex stages (extraction, entity resolution)
Keep custom for simple stages (scraping, staging)
Hybrid approach: best of both worlds

If Custom Sufficient:

Enhance custom workflow
Add observability (OpenTelemetry manually)
Improve error handling
Continue with proven approach

7. Koog Implementation Plan (If Adopted)

7.1 Architecture

┌─────────────────────────────────────────┐
│         Import API Endpoints             │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│      ImportPipelineService              │
│  (Orchestrates Koog agents)            │
└──────┬──────────┬──────────┬───────────┘
       │          │          │
       ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Extraction│ │  Entity  │ │Validation│
│   Agent   │ │Resolution│ │  Agent   │
│  (Koog)   │ │  Agent   │ │  (Koog)  │
│           │ │  (Koog)  │ │          │
└──────────┘ └──────────┴──────────┘
                   │
       ┌───────────▼───────────┐
       │   Custom Services     │
       │  (Scraping, Staging)  │
       └──────────────────────┘

7.2 Key Components

Extraction Agent:

Uses Gemini for content extraction
Tool: extract_krithi_metadata
Handles variable HTML structures
Returns structured JSON

Entity Resolution Agent:

Tools: resolve_composer, resolve_raga, resolve_deity, resolve_temple
Fuzzy matching logic
Confidence scoring
Returns mapped entities

Validation Agent:

Tool: validate_krithi_data
Quality checks
Musicological validation (optional)
Returns validation results

7.3 Integration Points

With Existing Services:

WebScrapingService: Called before Koog agents
TransliterationService: Called as tool or after extraction
Database: Koog tools call repositories
Import Review UI: Unchanged (works with staged data)

8. Cost-Benefit Analysis

8.1 Koog Adoption Costs

Development:

Learning curve: 1-2 weeks for team
POC implementation: 1-2 weeks
Full integration: 2-3 weeks
Total: 4-7 weeks

Operational:

Framework maintenance
Monitoring setup
Debugging complexity
Ongoing: Medium

Dependencies:

Additional library
Potential version conflicts
Framework updates
Risk: Low-Medium

8.2 Koog Benefits

Short-Term:

Better error handling (retry, persistence)
Improved observability
Workflow visualization

Long-Term:

Provider flexibility
Complex workflow support
Enterprise-grade features
Community support

Quantifiable:

Error Recovery: 20-30% reduction in manual intervention
Debugging Time: 30-40% reduction with better tracing
Workflow Changes: 50% faster to modify workflows

8.3 Custom Solution Costs

Development:

Implementation: 2-3 weeks
Error handling: 1 week
Observability: 1 week
Total: 4-5 weeks

Operational:

Own code maintenance
Manual observability setup
Custom retry logic
Ongoing: Medium

Dependencies:

No new dependencies
Full control
Risk: Low

8.4 Custom Solution Benefits

Short-Term:

Fast implementation
Team familiarity
Full control

Long-Term:

No framework constraints
Direct optimization
Consistent with codebase

Quantifiable:

Initial Speed: 2-3 weeks faster
Learning Curve: Minimal
Performance: 10-15% faster (no framework overhead)

9. Risk Assessment

9.1 Koog Risks

Risk	Impact	Probability	Mitigation
Learning Curve	Medium	High	Training, documentation, POC
Framework Changes	Medium	Low	Version pinning, monitoring
Over-Engineering	Low	Medium	Start with POC, evaluate value
Performance Overhead	Low	Medium	Benchmark, optimize if needed
Team Resistance	Medium	Low	Involve team in decision

9.2 Custom Solution Risks

Risk	Impact	Probability	Mitigation
Missing Features	Medium	Medium	Add as needed, consider Koog later
Error Handling Complexity	Medium	Medium	Use proven patterns, test thoroughly
Observability Gaps	Low	Medium	Add OpenTelemetry manually
Maintenance Burden	Low	Low	Well-structured code, good tests

10. Recommendations

10.1 Immediate Recommendation

Start with Custom Workflow:

Build coroutine-based pipeline
Implement basic retry and error handling
Add simple logging
Get to production quickly

Rationale:

Faster time to market
Lower risk
Team familiarity
Meets immediate needs

10.2 Evaluation Phase

Build Koog POC (After Custom):

Choose extraction stage for POC
Implement same functionality with Koog
Compare side-by-side
Document findings
Team discussion and decision

Evaluation Criteria:

Performance (latency, throughput)
Maintainability (code clarity, changes)
Observability (tracing, debugging)
Error handling (retry effectiveness)
Developer experience (learning curve, DX)

10.3 Decision Framework

Adopt Koog If:

✅ POC shows clear benefits
✅ Team comfortable with framework
✅ Complex workflows benefit from graphs
✅ Observability significantly better
✅ Long-term value clear

Stick with Custom If:

✅ Custom solution meets all needs
✅ Performance is critical
✅ Team prefers full control
✅ Koog adds unnecessary complexity
✅ Maintenance concerns

11. Conclusion

Koog offers compelling features for complex import workflows, but may not be necessary initially. The recommended approach:

Phase 1: Custom workflow (fast, low risk, meets needs)
Phase 2: Koog POC (evaluate value, compare)
Phase 3: Decision (adopt if value clear, enhance custom otherwise)

Key Insight: Don’t optimize prematurely. Build what works, then evaluate if Koog adds value for specific pain points.

Success Factors:

Start simple, add complexity as needed
Evaluate based on real usage
Involve team in decision
Keep options open (hybrid approach possible)

12. References

Documentation home · Feature status