Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stevekrenzel merged 12 commits into from
Dec 22, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
5d46bb1
refactor: rename Reranker to Intent and unify constructor options
stevekrenzel Dec 22, 2025
39c29ab
feat(groq): repair invalid JSON via guided retries
stevekrenzel Dec 22, 2025
60f258c
feat(intent): add optional explain output with per-item reasoning
stevekrenzel Dec 22, 2025
ee2fdfe
feat(intent): configurable score range and relax schema constraints
stevekrenzel Dec 22, 2025
0334067
test(int): expand Intent real-wire integration coverage
stevekrenzel Dec 22, 2025
db2d0c2
feat(config): replace INTENT_MODEL with provider selection
stevekrenzel Dec 22, 2025
89ccb87
test(int): add default-constructor Intent examples
stevekrenzel Dec 22, 2025
354b567
test(int): improve integration test descriptions
stevekrenzel Dec 22, 2025
206f5f7
feat(intent): add filter() and choice() APIs
stevekrenzel Dec 22, 2025
8e18648
feat(groq): replace temperature with reasoningEffort
stevekrenzel Dec 22, 2025
89faeaf
docs(readme): quickstart + config clarity; refine explanations
stevekrenzel Dec 22, 2025
e2fddb1
chore(package): publish as @with-logic/intent
stevekrenzel Dec 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/pr-review-prompt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ function process(data: Data | null) {

### Naming Conventions

- **Classes and Types**: PascalCase (`Reranker`, `LlmClient`)
- **Classes and Types**: PascalCase (`Intent`, `LlmClient`)
- **Functions and Variables**: camelCase (`buildMessages`, `candidateKey`)
- **Constants**: UPPER_SNAKE_CASE (`BATCH_SIZE`, `TIMEOUT_MS`)
- **Test files**: `*.unit.test.ts` or `*.int.test.ts`
Expand Down
8 changes: 5 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Intent is a TypeScript library that uses LLMs to rerank arbitrary items based on

### Core Reranking Flow

The `Reranker` class orchestrates the entire reranking process:
The `Intent` class orchestrates the entire ranking process:

1. **Preparation** (`prepareCandidates`): Normalizes items into a consistent shape with key/summary/index
2. **Batching** (`batchProcess` in batches.ts): Splits candidates into batches, merges tiny trailing batches to avoid inefficient LLM calls
Expand All @@ -75,14 +75,16 @@ All config lives in config.ts using lib/config helpers:
- Environment variables: `INTENT_MODEL`, `INTENT_TIMEOUT_MS`, `INTENT_RELEVANCY_THRESHOLD`, `INTENT_BATCH_SIZE`, `INTENT_TINY_BATCH_FRACTION`
- Groq-specific: `GROQ_API_KEY`, `GROQ_DEFAULT_MODEL`, `GROQ_DEFAULT_TEMPERATURE`
- Config is loaded automatically via `dotenv/config` import at top of config.ts
- Reranker constructor accepts overrides as third parameter
- Intent constructor accepts options as a single optional object

**Config Naming Convention**: By design, config keys in `CONFIG` use `UPPER_SNAKE_CASE` to mirror their environment variable names (e.g., `CONFIG.INTENT.MODEL` matches `INTENT_MODEL`). The user-facing API uses `camelCase` (e.g., `options.model`). This intentional distinction keeps config keys aligned with environment variables while providing an ergonomic API. Internal code converts between these formats as needed.

### Key Design Patterns

- **Stable fallbacks**: Any failure (LLM error, timeout, invalid response) returns items in original order
- **Duplicate key handling**: Internal disambiguation using `"Key (idx)"` suffix
- **Strict typing**: Uses TypeScript strict mode with `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
- **Generic item support**: Reranker is `Reranker<T>` with user-provided key/summary extractors
- **Generic item support**: Intent is `Intent<T>` with user-provided key/summary extractors
- **Zero/one-item fast path**: Avoids LLM calls when unnecessary

## Testing Strategy
Expand Down
Loading