Phase/tool integrations

[Ryanakml]

Summary by CodeRabbit

• New Features

  • Added LLM tools for order status lookup, product information, shipping estimates, and support ticket creation with built-in error handling and user-friendly fallback messaging.
  • Added resilience mechanisms (retry logic, timeouts, and circuit breaker) to improve tool reliability and recovery from transient failures.
  • Added knowledge document types for RAG (Retrieval Augmented Generation) support.

• Tests

  • Added comprehensive test suites for LLM tools and reliability utilities.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 31a94e72-d55c-4cd9-a8c7-6f267e94c4ad

📥 Commits

Reviewing files that changed from the base of the PR and between 36a65fe and 707efa1.

⛔ Files ignored due to path filters (4)

• packages/shared/src/index.d.ts.map is excluded by !**/*.map
• packages/shared/src/index.js.map is excluded by !**/*.map
• packages/shared/src/rag.d.ts.map is excluded by !**/*.map
• packages/shared/src/rag.js.map is excluded by !**/*.map

📒 Files selected for processing (11)

• packages/llm/__tests__/tools.test.ts
• packages/llm/src/index.ts
• packages/llm/src/tools/__tests__/reliability.test.ts
• packages/llm/src/tools/__tests__/tools.test.ts
• packages/llm/src/tools/index.ts
• packages/llm/src/tools/reliability.ts
• packages/llm/src/tools/schemas.ts
• packages/shared/src/index.d.ts
• packages/shared/src/index.js
• packages/shared/src/rag.d.ts
• packages/shared/src/rag.js

---

📝 Walkthrough

Walkthrough

This PR introduces a comprehensive LLM tools module with schema-validated inputs, reliability utilities (timeout, retry, circuit breaker), and business logic tools wrapped with error handling. It also adds type definitions for RAG (knowledge documents, chunks, ingestion sources) to the shared package.

Changes

Cohort / File(s)	Summary
LLM Tool Schemas packages/llm/src/tools/schemas.ts	Zod schemas for tool inputs: OrderStatusLookup, ProductInformation, ShippingEstimate, and SupportTicketCreation with field validation and optional configuration.
Reliability Utilities packages/llm/src/tools/reliability.ts	Timeout enforcement via withTimeout, transient error detection, exponential backoff retry via withRetry, and stateful CircuitBreaker with CLOSED/OPEN/HALF_OPEN state transitions.
Tool Implementations packages/llm/src/tools/index.ts	Five business tools (orderStatusLookup, productInformation, shippingEstimate, supportTicketCreation, escalateToHuman) wrapped with CircuitBreaker, Retry, and Timeout layers; includes fallback error handling and observability logging.
Tool Tests packages/llm/src/tools/__tests__/reliability.test.ts, packages/llm/src/tools/__tests__/tools.test.ts	Comprehensive unit tests for reliability utilities (timeout, retry, circuit breaker state transitions) and integration tests for tool execution with mocked wrappers and side effects.
Schema Tests packages/llm/__tests__/tools.test.ts	Validation tests for all four schemas with valid/invalid payloads; verification of tool stub returns as parseable JSON with expected fields.
Export Updates packages/llm/src/index.ts	Re-exports tools module to expose schemas, reliability utilities, and tool implementations.
RAG Type Definitions packages/shared/src/rag.d.ts, packages/shared/src/rag.js	TypeScript type declarations for KnowledgeDocument, KnowledgeChunk, and IngestionSource; minimal module stub in JS file.
Shared Package Exports packages/shared/src/index.d.ts, packages/shared/src/index.js	Re-export RAG types and declarations from ./rag.js.

Sequence Diagram

sequenceDiagram
    actor User
    participant Tool
    participant CircuitBreaker
    participant Retry
    participant Timeout
    participant BusinessLogic

    User->>Tool: Call tool with input
    Tool->>Tool: Validate input via schema
    Tool->>CircuitBreaker: Execute wrapped function
    
    alt CircuitBreaker state CLOSED
        CircuitBreaker->>Retry: Guard passes, execute
        Retry->>Timeout: Attempt with exponential backoff
        
        alt Within timeout
            Timeout->>BusinessLogic: Execute core logic
            BusinessLogic-->>Timeout: Success or transient error
            
            alt Transient error and attempts remain
                Timeout-->>Retry: Transient error
                Retry->>Retry: Exponential backoff delay
                Retry->>Timeout: Retry attempt
            else Success
                Timeout-->>Retry: Result
                Retry-->>CircuitBreaker: Success
                CircuitBreaker->>CircuitBreaker: Reset failure count
                CircuitBreaker-->>Tool: Result
            else Max retries exhausted
                Retry-->>CircuitBreaker: Final error
                CircuitBreaker->>CircuitBreaker: Increment failure count
            end
        else Timeout exceeded
            Timeout-->>Retry: TimeoutError
            Retry-->>CircuitBreaker: TimeoutError
        end
        
        alt Failure threshold reached
            CircuitBreaker->>CircuitBreaker: Transition to OPEN
        end
    else CircuitBreaker state OPEN
        CircuitBreaker-->>Tool: CircuitBreakerError
    else CircuitBreaker state HALF_OPEN
        CircuitBreaker->>Retry: Allow single attempt
    end
    
    Tool->>Tool: Handle errors with fallback message
    Tool-->>User: Return result or fallback JSON

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Phase/langchain agent runtime #5 — Modifies packages/llm/src/index.ts to add re-exports, overlapping with this PR's export surface changes.

Poem

🐰 Hops through code with tools so bright,
Schemas validate, retry and timeout fight,
Circuit breakers guard the flow,
Reliability wrappers steal the show,
From RAG's knowledge deep below! ✨

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch phase/tool-integrations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}