Intent ergonomics overhaul: unified API, explainable outputs, and smarter Groq defaults

[stevekrenzel]

Summary

This PR renames and consolidates the core reranking API around a single Intent class, adds higher-level helpers (filter() and choice()), and introduces optional
per-item explanations for more transparent results. It also improves Groq provider behavior (reasoning effort + guided retries to repair invalid JSON), expands
configuration/provider selection, and significantly strengthens test coverage (unit + real-wire integration).

Key Changes

• API ergonomics
  • Rename Reranker → Intent and unify constructor configuration into a single options object.
  • Add new high-level APIs: filter() (relevancy subset) and choice() (pick exactly one).
• Explainability
  • Add optional explain output with per-item reasoning (schema/prompt updates to support explanation alongside scores/decisions).
• Scoring + schema flexibility
  • Make score range configurable (minScore/maxScore) and relax schema constraints accordingly.
  • Expand schema support for ranking, filtering, and single-choice selection.
• Config + provider selection
  • Replace INTENT_MODEL-style config with explicit provider selection + clearer defaults.
• Groq provider improvements
  • Replace temperature usage with reasoningEffort.
  • Add guided retry/repair to handle invalid JSON responses.
• Tests
  • Add/expand unit tests for new APIs and extractors/config helpers.
  • Expand integration tests (including default constructor examples and improved descriptions).
• Packaging/docs touch-ups
  • Publish package as @with-logic/intent and align prompts/naming references.

Notes / Breaking Changes

• Reranker is removed in favor of Intent (constructor shape and method names updated accordingly).
• LLM call config changes from temperature → reasoningEffort (Groq path).

[claude]

Claude finished @stevekrenzel's task —— View job

---

PR Review: Intent Ergonomics Overhaul ✅

Comprehensive code review completed against Intent library engineering standards.

---

Executive Summary

This is a high-quality PR that delivers substantial improvements to the Intent library. The architectural changes are sound, documentation is comprehensive, and the code demonstrates strong engineering discipline. Tests pass with 100% coverage, and both linting and type checking succeed.

However, there is one critical code style violation that must be addressed: several instances of single-line if statements without braces, which directly violates the stated coding standards in CLAUDE.md.

---

Critical Issues (Must Fix)

1. Missing Braces on Single-Line If Statements

Location: src/intent.ts:616, 643, 677, 789 and src/providers/groq.ts:227-228, 301-302, 306-307

The code uses single-line if statements without braces, which directly violates CLAUDE.md's core principle: "Always Use Braces: No single-line if statements, even for simple returns."

// ❌ Current code (src/intent.ts:616)
if (data == null || typeof data !== "object") return null;

// ✅ Required style
if (data == null || typeof data !== "object") {
  return null;
}

Affected lines in intent.ts:

• Line 616: if (data == null || typeof data !== "object") return null;
• Line 643: if (data == null || typeof data !== "object") return null;
• Line 677: if (selectedKey === "") return null;
• Line 789: if (b.score !== a.score) return b.score - a.score;

Affected lines in groq.ts:

• Lines 227-228: if (state.remaining <= 1) { return undefined; } (braces present but single line)
• Lines 301-302: if (!serverError) { return undefined; } (braces present but single line)
• Lines 306-307: if (code !== "json_validate_failed") { return undefined; } (braces present but single line)

Why this matters: The coding standards explicitly require braces on all if statements for consistency, readability, and to prevent future bugs when someone adds a second line without noticing the missing braces. The examples in CLAUDE.md show each brace on its own line.

---

Code Quality Strengths

✅ Excellent Function Sizes

All functions are under 30 lines in the core implementation files (intent.ts, groq.ts, extractors.ts). This exceeds the target and demonstrates excellent code organization through small, focused functions.

✅ Comprehensive Documentation

Every function has proper JSDoc with:

• Clear descriptions
• @param annotations with detailed explanations
• @returns documentation
• @throws documentation where applicable
• @example blocks for public APIs
• @private markers for internal functions

The documentation quality is exemplary, especially in src/intent.ts:20-51, 174-221.

✅ Strong TypeScript Type Safety

• No any types without justification (groq.ts:365, 369 use any for groq-sdk interop with comment explaining why)
• Proper use of generics (e.g., Intent<T>)
• Type narrowing with guards (e.g., typeof checks)
• Overloaded method signatures for explain parameter (intent.ts:265-281)
• Strict type checking passes with zero errors

✅ Excellent Error Handling

• Graceful degradation with fallbacks (intent.ts:317-325, preserving original order on errors)
• Comprehensive error messages with context (intent.ts:139-141, 167-169)
• Proper error type checking: error instanceof Error (intent.ts:318)
• Structured retry logic in Groq provider (groq.ts:436-465)

✅ Early Returns and Minimal Nesting

The code consistently uses early returns for fast paths:

• Zero/one candidate optimizations (intent.ts:283-293, 368-378, 436-446)
• Null checks with early returns (intent.ts:616, 643, 677, 722-725, 746-748)
• Maximum nesting depth stays at 2-3 levels

✅ 100% Test Coverage

All unit tests pass with complete statement, branch, function, and line coverage. Integration tests provide additional real-world validation with 165 tests passing.

---

Architecture Review

API Design: Excellent

The refactoring from Reranker to Intent with unified options object significantly improves ergonomics. The addition of filter() and choice() methods provides clear, purpose-driven APIs.

Particularly well-designed:

• Overloaded signatures for explain parameter provide type-safe distinction between T[] and Array<{ item: T; explanation: string }> returns
• Tournament strategy in choice() for handling large candidate sets (intent.ts:451-477)
• Consistent fallback behavior across all methods

Provider Architecture: Solid

The Groq provider improvements are substantial:

• JSON repair logic (groq.ts:198-241) is clever and well-structured
• Breaking repair logic into focused helper functions demonstrates excellent code organization
• Regex-based extraction of failed generation from error messages (groq.ts:284-285) is pragmatic
• Guided retry with repair messages (groq.ts:199-214) elegantly handles schema validation failures

Configuration System: Clear

The CONFIG object with environment variable mapping is well-structured. The distinction between UPPER_SNAKE_CASE config keys and camelCase API options is intentional and documented (CLAUDE.md explains this design choice).

---

Minor Observations (Non-Blocking)

File Sizes

Two files exceed the 300-line guideline:

• src/intent.ts: 823 lines ⚠️
• src/providers/groq.ts: 471 lines ⚠️

While these exceed the <300 line guideline, both files remain highly cohesive:

• intent.ts: Single Intent class with three public methods (rank, filter, choice) and supporting private helpers. Breaking this apart would reduce cohesion.
• groq.ts: Single provider implementation with retry/repair logic. Could potentially split repair logic into separate file, but current organization is acceptable.

Recommendation: Accept as-is. Both files maintain single, clear purposes despite their length.

Naming Clarity

Generally excellent, but one minor suggestion:

• buildRepairRetry (groq.ts:226) - name suggests it builds a retry, but it also checks if retries remain. Consider tryBuildRepairRetry or maybeBuildRepairRetry to signal the possibility of undefined return.

This is a nitpick and non-blocking.

Test Organization

Test files are well-structured with:

• Clear top-level describe blocks
• Helper functions for creating test fixtures (makeCtx in intent.unit.test.ts:9-27)
• Proper isolation between tests
• Descriptive test names following the pattern "method() description"

---

Summary and Recommendations

Overall Assessment: Strong PR with high code quality, comprehensive tests, and sound architecture. The refactoring from Reranker to Intent is well-executed.

Must address before merge:

1. Add braces (with each brace on its own line) to single-line if statements in src/intent.ts (lines 616, 643, 677, 789)
2. Verify brace formatting in src/providers/groq.ts matches the multi-line style shown in CLAUDE.md examples

After addressing the bracing issue, this PR will be ready to merge. The bracing fix is straightforward and mechanical - no design changes needed.

---

Final Checklist Against Requirements

• No functions over 50 lines (all under 30!)
• All if statements use braces ← Must fix
• All functions have JSDoc documentation
• No any types without justification
• No hardcoded values that should be config
• No commented-out code
• No console.log statements
• Type checking passes
• Linting passes
• Tests pass with 100% coverage
• Build succeeds

Score: 11/12 - Excellent work! Just needs the bracing fix to meet 100% of the coding standards.

---