@djangocfg/llm 2.1.164

package/README.md

@@ -0,0 +1,181 @@
+# @djangocfg/llm
+
+LLM client with SDKRouter, OpenAI, and Anthropic support. Includes JSON translator with validation.
+
+## Installation
+
+```bash
+pnpm add @djangocfg/llm
+```
+
+## Quick Start
+
+```ts
+import { createLLMClient, Model, createTranslator } from '@djangocfg/llm'
+
+// Auto-detect from env (SDKRouter preferred)
+const llm = createLLMClient()
+
+// With model alias
+const llm = createLLMClient({ model: Model.balanced({ code: true }) })
+
+// Simple chat
+const response = await llm.chat('Hello!')
+
+// JSON response
+const data = await llm.json<{ name: string }>('Return a user object')
+
+// Translate JSON
+const translator = createTranslator(llm)
+const result = await translator.translate({ title: 'Hello' }, 'ru')
+console.log(result.data) // { title: 'Привет' }
+```
+
+## Environment Variables
+
+```bash
+# SDKRouter (recommended)
+SDKROUTER_API_KEY=sk-...
+
+# Or OpenAI
+OPENAI_API_KEY=sk-...
+
+# Or Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Priority: `SDKROUTER_API_KEY` > `OPENAI_API_KEY` > `ANTHROPIC_API_KEY`
+
+## Model Aliases (SDKRouter)
+
+SDKRouter uses smart model aliases to select the best model for your task:
+
+```ts
+import { Model, ModelPresets } from '@djangocfg/llm'
+
+// Tier methods
+Model.cheap()                    // '@cheap' - Cheapest
+Model.balanced()                 // '@balanced' - Best value (default)
+Model.smart()                    // '@smart' - Highest quality
+Model.fast()                     // '@fast' - Lowest latency
+
+// With capabilities
+Model.cheap({ vision: true })    // '@cheap+vision'
+Model.balanced({ tools: true })  // '@balanced+tools'
+Model.smart({ json: true })      // '@smart+json'
+
+// With categories
+Model.balanced({ code: true })   // '@balanced+code'
+Model.smart({ reasoning: true }) // '@smart+reasoning'
+
+// Pre-built presets
+ModelPresets.translation   // '@cheap+json' - For translation tasks
+ModelPresets.code          // '@balanced+code' - For code generation
+ModelPresets.reasoning     // '@smart+reasoning' - For complex reasoning
+```
+
+### Available Tiers
+
+- `cheap` - Cheapest available model
+- `budget` - Budget-friendly with decent quality
+- `standard` - Standard tier
+- `balanced` - Best quality/price ratio (recommended)
+- `smart` - Highest quality model
+- `fast` - Lowest latency model
+- `premium` - Top-tier premium model
+
+### Available Capabilities
+
+- `vision` - Image understanding
+- `tools` - Function/tool calling
+- `agents` - Agent tool calling (verified)
+- `json` - JSON mode
+- `streaming` - Streaming support
+- `long` - Long context (128k+)
+- `image` - Image generation
+
+### Available Categories
+
+- `code` - Code generation
+- `reasoning` - Reasoning & math
+- `creative` - Creative writing
+- `chat` - Conversational
+- `analysis` - Analysis & extraction
+
+## API
+
+### createLLMClient(config?)
+
+```ts
+const llm = createLLMClient({
+  provider: 'sdkrouter',   // 'sdkrouter' | 'openai' | 'anthropic'
+  apiKey: 'sk-...',        // Optional, uses env
+  model: '@balanced',      // Default model
+  temperature: 0.1,
+  maxTokens: 4096,
+})
+```
+
+### llm.chat(prompt, options?)
+
+```ts
+const response = await llm.chat('Translate to Russian: Hello', {
+  temperature: 0,
+  system: 'You are a professional translator',
+})
+
+console.log(response.content)  // 'Привет'
+console.log(response.usage)    // { promptTokens, completionTokens, totalTokens }
+```
+
+### llm.json<T>(prompt, options?)
+
+```ts
+interface User {
+  name: string
+  email: string
+}
+
+const user = await llm.json<User>('Return a sample user object')
+```
+
+### createTranslator(llm)
+
+```ts
+const translator = createTranslator(llm)
+
+const result = await translator.translate(
+  { title: 'Hello', items: ['One', 'Two'] },
+  'ru',
+  {
+    sourceLanguage: 'en',
+    maxRetries: 2
+  }
+)
+
+if (result.valid) {
+  console.log(result.data) // { title: 'Привет', items: ['Один', 'Два'] }
+} else {
+  console.error('Errors:', result.errors)
+}
+```
+
+## Providers
+
+### SDKRouter (Default)
+
+- Base URL: `https://llm.sdkrouter.com/v1`
+- Uses smart model aliases (@cheap, @balanced, @smart)
+- Automatically selects best model for capabilities
+
+### OpenAI
+
+Models: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-3.5-turbo`
+
+### Anthropic
+
+Models: `claude-3-5-sonnet-latest`, `claude-3-5-haiku-latest`, `claude-3-opus-latest`
+
+## License
+
+MIT