Agent Guidelines

This file provides guidance to agents when working with code in this repository.

Build Commands

npm install          # Install dependencies
npm run build        # Build all outputs (CJS, ESM, and types)
npm run build:cjs    # Build CommonJS output only
npm run build:esm    # Build ESM output only
npm run build:types  # Build type declarations only

Test Commands

npm test              # Run all tests (unit + integration)
npm run test:unit     # Run unit tests only
npm run test:llama    # Run Llama.cpp integration tests only
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

Important: Always run npm test after making changes to verify nothing is broken. Tests are located in the test/ folder.

Tests are written using Vitest and cover:

• Provider selection logic (OpenAI, Cloudflare, Ollama priority)
• Error handling for all providers
• Message format conversion for Llama.cpp
• API request formatting

Architecture

This is a TypeScript npm package (@derogab/llm-proxy) that provides a unified interface for multiple LLM providers. The entire implementation is in a single file: src/index.ts.

Provider Selection

The generate() function automatically selects a provider based on environment variables in this priority order:

1. OpenAI - if OPENAI_API_KEY is set
2. Cloudflare AI - if CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_AUTH_KEY, and CLOUDFLARE_MODEL are all set
3. Ollama - if OLLAMA_URI is set
4. Llama.cpp - if LLAMA_CPP_MODEL_PATH is set

Build Output

The package builds to three output formats:

• dist/cjs/ - CommonJS (for require())
• dist/esm/ - ES Modules (for import)
• dist/types/ - TypeScript declarations

Conventional Commits

This project follows the Conventional Commits specification.

Format

<type>: <description>

Types

Examples

feat: add support for new LLM provider
fix: resolve timeout issue with Ollama requests
docs: update README with configuration examples
refactor: simplify provider selection logic
test: add unit tests for error handling
chore: update dependencies

Breaking Changes

Add ! after the type for breaking changes:

feat!: change API response format

Proxy Collection

This package is part of a family of plug-and-play proxy packages:

• @derogab/llm-proxy - LLM provider proxy (this package)
• @derogab/stt-proxy - Speech-to-Text provider proxy

Important: Before implementing any changes, you MUST check the other projects in this family to see if similar changes have already been made. If so, follow the same structure, patterns, and specifications used there. This ensures consistency across all proxy packages in the long term.