@agents-eco/reasoning 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agents.eco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,365 @@
+<p align="center">
+  <img src="icon.png" alt="Reasoning Module" width="160" />
+</p>
+
+<h1 align="center">Reasoning Module</h1>
+
+<p align="center">
+  <strong>Multi-strategy reasoning for AI agents — ReAct, Chain-of-Thought, Tree-of-Thought.</strong><br/>
+  Built by <a href="https://agents.eco">agents.eco</a> — the decentralized AI agent economy.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agents-eco/reasoning"><img src="https://img.shields.io/npm/v/@agents-eco/reasoning?style=flat-square" alt="npm" /></a>
+  <a href="https://github.com/agents-eco/reasoning/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License" /></a>
+  <a href="https://github.com/agents-eco/reasoning"><img src="https://img.shields.io/github/stars/agents-eco/reasoning?style=flat-square" alt="GitHub stars" /></a>
+</p>
+
+```
+npm install @agents-eco/reasoning
+```
+
+---
+
+## Why This Exists
+
+Most agent frameworks treat reasoning as a black box. You send a prompt, you get an answer. There is no visibility into how the agent thinks, no way to swap strategies, and no structured output to inspect.
+
+This module makes reasoning explicit. Every thought, action, observation, and reflection is a structured step you can log, inspect, and hook into.
+
+Three reasoning strategies, each suited to different problem types:
+
+- **ReAct** — Multi-step reason-act loop with tool calling. Inspired by SmolAgents and Yao et al. 2022. Best for tasks requiring external information or computation.
+- **Chain-of-Thought (CoT)** — Sequential step-by-step reasoning with optional self-reflection. Best for logic, math, and analytical problems.
+- **Tree-of-Thought (ToT)** — Explores multiple reasoning paths using beam search. Best for complex problems with multiple valid approaches.
+
+Two backend categories:
+
+- **OpenAI-compatible** — OpenAI, Venice, Groq, Ollama, agents.eco. Any API that speaks the OpenAI chat format.
+- **HuggingFace** — Inference API (serverless), Inference Endpoints (dedicated), or self-hosted TGI. Run SmolAgents-recommended models like Qwen, Llama, DeepSeek.
+
+## Quick Start
+
+### ReAct with Tool Calling
+
+```typescript
+import { ReasoningEngine, veniceBackend } from "@agents-eco/reasoning";
+
+const engine = new ReasoningEngine(
+  veniceBackend(process.env.VENICE_API_KEY!, "qwen3-4b"),
+  { strategy: "react", maxSteps: 10 }
+);
+
+// Register tools
+engine.tool("search", {
+  name: "search",
+  description: "Search the web for information",
+  parameters: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+  },
+}, async ({ query }) => {
+  const res = await fetch(`https://api.duckduckgo.com/?q=${query}&format=json`);
+  const data = await res.json();
+  return data.AbstractText || "No results found.";
+});
+
+const result = await engine.reason("What is the population of Tokyo?");
+console.log(result.answer);
+console.log(`Steps: ${result.steps.length}, LLM calls: ${result.llmCalls}`);
+```
+
+### Chain-of-Thought
+
+```typescript
+import { ReasoningEngine, openaiBackend } from "@agents-eco/reasoning";
+
+const engine = new ReasoningEngine(
+  openaiBackend(process.env.OPENAI_API_KEY!, "gpt-4o"),
+  { strategy: "cot", reflection: true }
+);
+
+const result = await engine.chainOfThought(
+  "A bat and a ball cost $1.10 in total. The bat costs $1.00 more than the ball. How much does the ball cost?"
+);
+
+for (const step of result.steps) {
+  console.log(`[${step.type}] ${step.content}`);
+}
+// Thought: Let x = ball price...
+// Thought: x + (x + 1.00) = 1.10...
+// Answer: The ball costs $0.05
+```
+
+### Tree-of-Thought
+
+```typescript
+import { ReasoningEngine, groqBackend } from "@agents-eco/reasoning";
+
+const engine = new ReasoningEngine(
+  groqBackend(process.env.GROQ_API_KEY!, "llama-3.3-70b-versatile"),
+  { strategy: "tot" }
+);
+
+const result = await engine.treeOfThought(
+  "Design a sorting algorithm that is optimal for nearly-sorted arrays.",
+  { branchFactor: 3, maxDepth: 4, beamWidth: 2, scoringMethod: "llm" }
+);
+
+console.log(result.answer);
+console.log(`Explored ${result.steps.filter(s => s.type === "thought").length} branches`);
+```
+
+### HuggingFace / SmolAgents Models
+
+```typescript
+import { ReasoningEngine, hfInferenceBackend, SMOLAGENTS_MODELS } from "@agents-eco/reasoning";
+
+// Serverless Inference API
+const engine = new ReasoningEngine(
+  hfInferenceBackend(process.env.HF_TOKEN!, SMOLAGENTS_MODELS.qwen72b),
+  { strategy: "react", maxSteps: 8 }
+);
+
+const result = await engine.reason("Explain the Riemann hypothesis.");
+```
+
+```typescript
+import { hfEndpointBackend, tgiBackend } from "@agents-eco/reasoning";
+
+// Dedicated Inference Endpoint
+const endpoint = hfEndpointBackend(
+  process.env.HF_TOKEN!,
+  "https://xyz.endpoints.huggingface.cloud"
+);
+
+// Self-hosted TGI
+const local = tgiBackend("http://localhost:8080");
+```
+
+### Local with Ollama
+
+```typescript
+import { ReasoningEngine, ollamaBackend } from "@agents-eco/reasoning";
+
+const engine = new ReasoningEngine(
+  ollamaBackend("llama3.2"),
+  { strategy: "cot", reflection: true }
+);
+
+const result = await engine.reason("What are the trade-offs between B-trees and LSM-trees?");
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                   ReasoningEngine                         │
+│                                                           │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                   Strategies                         │  │
+│  │                                                      │  │
+│  │  ┌──────────┐  ┌──────────────┐  ┌───────────────┐  │  │
+│  │  │  ReAct   │  │ Chain-of-    │  │  Tree-of-     │  │  │
+│  │  │          │  │ Thought      │  │  Thought      │  │  │
+│  │  │ Thought  │  │              │  │               │  │  │
+│  │  │ Action   │  │ Step 1       │  │    [root]     │  │  │
+│  │  │ Observe  │  │ Step 2       │  │   /  |  \     │  │  │
+│  │  │ Reflect  │  │ Step N       │  │  A   B   C    │  │  │
+│  │  │ Plan     │  │ Reflect      │  │ / \     |     │  │  │
+│  │  │ Answer   │  │ Answer       │  │ D  E    F     │  │  │
+│  │  └──────────┘  └──────────────┘  └───────────────┘  │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                           │                               │
+│  ┌────────────────────────▼────────────────────────────┐  │
+│  │                    Tools                             │  │
+│  │  search, calculate, fetch, execute, ...              │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                           │                               │
+│  ┌────────────────────────▼────────────────────────────┐  │
+│  │                  LLM Backends                        │  │
+│  │                                                      │  │
+│  │  OpenAI  Venice  Groq  Ollama  agents.eco            │  │
+│  │  HuggingFace (Inference API / Endpoints / TGI)       │  │
+│  └─────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Strategies
+
+### ReAct (Reason + Act)
+
+The default strategy. Implements the multi-step reasoning loop from SmolAgents and the ReAct paper (Yao et al., 2022).
+
+Each step follows: **Thought** -> **Action** -> **Observation**, with optional **Reflection** and **Planning**.
+
+| Feature | Description |
+|---------|-------------|
+| Tool calling | Register handlers, agent decides when to use them |
+| Reflection | Self-evaluation every N steps (configurable) |
+| Planning | Initial plan + periodic revision |
+| Self-correction | Agent retries on tool errors with different approach |
+| Max steps | Hard limit to prevent infinite loops |
+
+### Chain-of-Thought (CoT)
+
+Single-pass sequential reasoning. The LLM breaks the problem into numbered steps and arrives at an answer.
+
+| Feature | Description |
+|---------|-------------|
+| Step parsing | Extracts individual reasoning steps from output |
+| Self-reflection | Optional second pass to verify the chain |
+| Revision | If reflection finds errors, produces a corrected answer |
+
+### Tree-of-Thought (ToT)
+
+Explores multiple reasoning paths in parallel using beam search.
+
+| Feature | Description |
+|---------|-------------|
+| Branch generation | LLM generates N distinct next steps at each node |
+| Branch scoring | LLM-based or heuristic scoring (0-1) |
+| Beam search | Keeps top-k branches at each depth |
+| Path extraction | Best path is used to generate the final answer |
+
+## Hooks
+
+Intercept every step of the reasoning process:
+
+```typescript
+const engine = new ReasoningEngine(backend, {
+  strategy: "react",
+  maxSteps: 10,
+  hooks: {
+    onStep: (step) => console.log(`[${step.type}] ${step.content.slice(0, 80)}`),
+    onThought: (thought) => console.log(`Thinking: ${thought}`),
+    onAction: (tool, args) => console.log(`Calling: ${tool}(${JSON.stringify(args)})`),
+    onObservation: (result) => console.log(`Got: ${result.slice(0, 80)}`),
+    onReflection: (reflection) => console.log(`Reflecting: ${reflection}`),
+    onPlan: (plan) => console.log(`Plan: ${plan}`),
+    onAnswer: (answer) => console.log(`Answer: ${answer}`),
+    onError: (error) => console.error(`Error: ${error.message}`),
+  },
+});
+```
+
+## SmolAgents-Recommended Models
+
+Pre-configured model constants for HuggingFace:
+
+| Key | Model | Notes |
+|-----|-------|-------|
+| `qwen72b` | Qwen/Qwen2.5-72B-Instruct | Best open reasoning model |
+| `qwen32b` | Qwen/Qwen2.5-32B-Instruct | Good balance of speed and quality |
+| `qwen7b` | Qwen/Qwen2.5-7B-Instruct | Fast, good for simple tasks |
+| `llama70b` | meta-llama/Llama-3.3-70B-Instruct | Strong reasoning, open weights |
+| `llama8b` | meta-llama/Llama-3.1-8B-Instruct | Fast Llama variant |
+| `deepseek` | deepseek-ai/DeepSeek-R1-Distill-Qwen-32B | Code-focused reasoning |
+| `mistral` | mistralai/Mistral-Small-24B-Instruct-2501 | Compact but capable |
+
+```typescript
+import { SMOLAGENTS_MODELS } from "@agents-eco/reasoning";
+console.log(SMOLAGENTS_MODELS.qwen72b); // "Qwen/Qwen2.5-72B-Instruct"
+```
+
+## Integration with Open Agentic Framework
+
+Use as the reasoning backend for [@agents-eco/open-agentic-framework](https://github.com/agents-eco/open-agentic-framework):
+
+```typescript
+import { Agent } from "@agents-eco/open-agentic-framework";
+import { ReasoningEngine, veniceBackend } from "@agents-eco/reasoning";
+
+const reasoning = new ReasoningEngine(
+  veniceBackend(process.env.VENICE_API_KEY!, "qwen3-4b"),
+  { strategy: "react", maxSteps: 8, reflection: true }
+);
+
+const agent = new Agent({
+  name: "reasoning-agent",
+  systemPrompt: "You are a thoughtful assistant that reasons step by step.",
+  provider: {
+    name: "venice",
+    apiKey: process.env.VENICE_API_KEY!,
+    baseUrl: "https://api.venice.ai/api/v1",
+    defaultModel: "qwen3-4b",
+  },
+  hooks: {
+    beforeRequest: async (messages) => {
+      // Use reasoning engine for complex queries
+      const lastMsg = messages[messages.length - 1];
+      if (lastMsg.role === "user" && lastMsg.content.length > 100) {
+        const result = await reasoning.reason(lastMsg.content);
+        messages.push({
+          role: "system",
+          content: `Reasoning trace:\n${result.steps.map(s => `[${s.type}] ${s.content}`).join("\n")}`,
+        });
+      }
+      return messages;
+    },
+  },
+});
+```
+
+## API Reference
+
+### `ReasoningEngine`
+
+| Method | Description |
+|--------|-------------|
+| `reason(task, overrides?)` | Run reasoning with configured strategy |
+| `react(task, overrides?)` | Run ReAct reasoning |
+| `chainOfThought(task, overrides?)` | Run CoT reasoning |
+| `treeOfThought(task, overrides?)` | Run ToT reasoning |
+| `tool(name, def, handler)` | Register a tool |
+| `addTools(toolMap)` | Register multiple tools |
+| `setBackend(backend)` | Swap the LLM backend |
+| `setSystemPrompt(prompt)` | Set the system prompt |
+| `configure(config)` | Update configuration |
+| `hooks(hooks)` | Set event hooks |
+| `registerStrategy(strategy)` | Add a custom strategy |
+
+### `ReasoningResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `answer` | `string` | Final answer |
+| `steps` | `ReasoningStep[]` | All reasoning steps |
+| `strategy` | `StrategyType` | Strategy used |
+| `durationMs` | `number` | Total time |
+| `tokens` | `{prompt, completion, total}` | Token usage |
+| `llmCalls` | `number` | Number of LLM calls |
+| `toolCalls` | `number` | Number of tool calls |
+| `success` | `boolean` | Whether reasoning succeeded |
+
+### `ReasoningStep`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `StepType` | thought, action, observation, reflection, plan, revision, answer, error |
+| `content` | `string` | Step content |
+| `confidence` | `number` | Confidence score (0-1) |
+| `toolCalls` | `ToolCall[]` | Tool calls made |
+| `toolResults` | `ToolResult[]` | Tool results received |
+| `durationMs` | `number` | Step duration |
+
+## Contributing
+
+We welcome contributions. This project is early and there is room to shape its direction.
+
+- **Add a strategy** — Implement the `ReasoningStrategy` interface for new approaches (Reflexion, MCTS, etc.)
+- **Add a backend** — Anthropic, Cohere, local transformers
+- **Improve prompts** — Better ReAct/CoT/ToT prompts for specific model families
+- **Add benchmarks** — Test against GSM8K, MATH, HotpotQA, etc.
+- **Report issues** — Bug reports and feature requests help us prioritize
+
+## License
+
+MIT — [agents.eco](https://agents.eco)
+
+---
+
+<p align="center">
+  Built by <a href="https://agents.eco">agents.eco</a> — the decentralized AI agent economy.
+</p>

package/dist/backends/huggingface.d.ts

@@ -0,0 +1,75 @@
+import type { LLMBackend, ChatMessage, CompletionOptions, LLMResponse } from "../types.js";
+/**
+ * HuggingFace Inference API backend.
+ *
+ * Supports:
+ * - HuggingFace Inference API (serverless)
+ * - HuggingFace Inference Endpoints (dedicated)
+ * - Text Generation Inference (TGI) self-hosted
+ *
+ * Compatible with SmolAgents-style models that support chat completions.
+ * Works with models like Qwen, Llama, Mistral, DeepSeek, etc.
+ *
+ * API docs: https://huggingface.co/docs/api-inference/
+ */
+export declare class HuggingFaceBackend implements LLMBackend {
+    readonly name = "huggingface";
+    private apiKey;
+    private model;
+    private baseUrl;
+    private useTGI;
+    constructor(config: {
+        apiKey: string;
+        model: string;
+        /** Custom endpoint URL (for Inference Endpoints or self-hosted TGI) */
+        baseUrl?: string;
+        /** Use Text Generation Inference API format (default: auto-detect) */
+        useTGI?: boolean;
+    });
+    complete(messages: ChatMessage[], options?: CompletionOptions): Promise<LLMResponse>;
+    /**
+     * HuggingFace Inference API (serverless).
+     * Uses the /models/{model} endpoint with chat-style input.
+     */
+    private completeInferenceAPI;
+    /**
+     * Text Generation Inference (TGI) / Inference Endpoints.
+     * Uses the OpenAI-compatible /v1/chat/completions endpoint.
+     */
+    private completeTGI;
+}
+/**
+ * Use a HuggingFace model via the serverless Inference API.
+ * Good for: quick prototyping, small models, no infrastructure needed.
+ */
+export declare function hfInferenceBackend(apiKey: string, model?: string): HuggingFaceBackend;
+/**
+ * Use a HuggingFace Inference Endpoint (dedicated).
+ * Good for: production, guaranteed availability, custom models.
+ */
+export declare function hfEndpointBackend(apiKey: string, endpointUrl: string, model?: string): HuggingFaceBackend;
+/**
+ * Use a self-hosted TGI instance.
+ * Good for: full control, private deployment, GPU servers.
+ */
+export declare function tgiBackend(baseUrl?: string, model?: string): HuggingFaceBackend;
+/**
+ * SmolAgents-recommended models for reasoning tasks.
+ */
+export declare const SMOLAGENTS_MODELS: {
+    /** Best open reasoning model */
+    readonly qwen72b: "Qwen/Qwen2.5-72B-Instruct";
+    /** Good balance of speed and quality */
+    readonly qwen32b: "Qwen/Qwen2.5-32B-Instruct";
+    /** Fast, good for simple tasks */
+    readonly qwen7b: "Qwen/Qwen2.5-7B-Instruct";
+    /** Strong reasoning, open weights */
+    readonly llama70b: "meta-llama/Llama-3.3-70B-Instruct";
+    /** Fast Llama variant */
+    readonly llama8b: "meta-llama/Llama-3.1-8B-Instruct";
+    /** Code-focused reasoning */
+    readonly deepseek: "deepseek-ai/DeepSeek-R1-Distill-Qwen-32B";
+    /** Compact but capable */
+    readonly mistral: "mistralai/Mistral-Small-24B-Instruct-2501";
+};
+//# sourceMappingURL=huggingface.d.ts.map

package/dist/backends/huggingface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"huggingface.d.ts","sourceRoot":"","sources":["../../src/backends/huggingface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3F;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAU;gBAEZ,MAAM,EAAE;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,uEAAuE;QACvE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,sEAAsE;QACtE,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB;IAaK,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAO1F;;;OAGG;YACW,oBAAoB;IAuDlC;;;OAGG;YACW,WAAW;CAgD1B;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAoC,GAC1C,kBAAkB,CAEpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAAc,GACpB,kBAAkB,CAEpB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAE,MAAgC,EACzC,KAAK,GAAE,MAAc,GACpB,kBAAkB,CAEpB;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,gCAAgC;;IAEhC,wCAAwC;;IAExC,kCAAkC;;IAElC,qCAAqC;;IAErC,yBAAyB;;IAEzB,6BAA6B;;IAE7B,0BAA0B;;CAElB,CAAC"}

package/dist/backends/huggingface.js

@@ -0,0 +1,158 @@
+/**
+ * HuggingFace Inference API backend.
+ *
+ * Supports:
+ * - HuggingFace Inference API (serverless)
+ * - HuggingFace Inference Endpoints (dedicated)
+ * - Text Generation Inference (TGI) self-hosted
+ *
+ * Compatible with SmolAgents-style models that support chat completions.
+ * Works with models like Qwen, Llama, Mistral, DeepSeek, etc.
+ *
+ * API docs: https://huggingface.co/docs/api-inference/
+ */
+export class HuggingFaceBackend {
+    name = "huggingface";
+    apiKey;
+    model;
+    baseUrl;
+    useTGI;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.model = config.model;
+        this.useTGI = config.useTGI ?? false;
+        if (config.baseUrl) {
+            this.baseUrl = config.baseUrl.replace(/\/$/, "");
+            this.useTGI = config.useTGI ?? true;
+        }
+        else {
+            this.baseUrl = "https://api-inference.huggingface.co/models";
+        }
+    }
+    async complete(messages, options) {
+        if (this.useTGI) {
+            return this.completeTGI(messages, options);
+        }
+        return this.completeInferenceAPI(messages, options);
+    }
+    /**
+     * HuggingFace Inference API (serverless).
+     * Uses the /models/{model} endpoint with chat-style input.
+     */
+    async completeInferenceAPI(messages, options) {
+        const url = `${this.baseUrl}/${this.model}/v1/chat/completions`;
+        const body = {
+            model: this.model,
+            messages: messages.map((m) => ({ role: m.role, content: m.content })),
+            temperature: options?.temperature ?? 0.3,
+            max_tokens: options?.maxTokens ?? 2048,
+            stream: false,
+        };
+        if (options?.stop)
+            body.stop = options.stop;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            // Handle model loading
+            if (res.status === 503) {
+                throw new Error(`Model '${this.model}' is loading. Please retry in a few seconds. ${errText}`);
+            }
+            throw new Error(`HuggingFace API error (${res.status}): ${errText}`);
+        }
+        const data = await res.json();
+        const choice = data.choices[0];
+        return {
+            content: choice.message.content ?? "",
+            tokens: data.usage
+                ? { prompt: data.usage.prompt_tokens, completion: data.usage.completion_tokens }
+                : undefined,
+            finishReason: choice.finish_reason,
+        };
+    }
+    /**
+     * Text Generation Inference (TGI) / Inference Endpoints.
+     * Uses the OpenAI-compatible /v1/chat/completions endpoint.
+     */
+    async completeTGI(messages, options) {
+        const url = `${this.baseUrl}/v1/chat/completions`;
+        const body = {
+            model: this.model,
+            messages: messages.map((m) => ({ role: m.role, content: m.content })),
+            temperature: options?.temperature ?? 0.3,
+            max_tokens: options?.maxTokens ?? 2048,
+            stream: false,
+        };
+        if (options?.stop)
+            body.stop = options.stop;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(`TGI API error (${res.status}): ${errText}`);
+        }
+        const data = await res.json();
+        const choice = data.choices[0];
+        return {
+            content: choice.message.content ?? "",
+            tokens: data.usage
+                ? { prompt: data.usage.prompt_tokens, completion: data.usage.completion_tokens }
+                : undefined,
+            finishReason: choice.finish_reason,
+        };
+    }
+}
+// ── Pre-configured backends ─────────────────────────────
+/**
+ * Use a HuggingFace model via the serverless Inference API.
+ * Good for: quick prototyping, small models, no infrastructure needed.
+ */
+export function hfInferenceBackend(apiKey, model = "Qwen/Qwen2.5-72B-Instruct") {
+    return new HuggingFaceBackend({ apiKey, model });
+}
+/**
+ * Use a HuggingFace Inference Endpoint (dedicated).
+ * Good for: production, guaranteed availability, custom models.
+ */
+export function hfEndpointBackend(apiKey, endpointUrl, model = "tgi") {
+    return new HuggingFaceBackend({ apiKey, model, baseUrl: endpointUrl, useTGI: true });
+}
+/**
+ * Use a self-hosted TGI instance.
+ * Good for: full control, private deployment, GPU servers.
+ */
+export function tgiBackend(baseUrl = "http://localhost:8080", model = "tgi") {
+    return new HuggingFaceBackend({ apiKey: "", model, baseUrl, useTGI: true });
+}
+/**
+ * SmolAgents-recommended models for reasoning tasks.
+ */
+export const SMOLAGENTS_MODELS = {
+    /** Best open reasoning model */
+    qwen72b: "Qwen/Qwen2.5-72B-Instruct",
+    /** Good balance of speed and quality */
+    qwen32b: "Qwen/Qwen2.5-32B-Instruct",
+    /** Fast, good for simple tasks */
+    qwen7b: "Qwen/Qwen2.5-7B-Instruct",
+    /** Strong reasoning, open weights */
+    llama70b: "meta-llama/Llama-3.3-70B-Instruct",
+    /** Fast Llama variant */
+    llama8b: "meta-llama/Llama-3.1-8B-Instruct",
+    /** Code-focused reasoning */
+    deepseek: "deepseek-ai/DeepSeek-R1-Distill-Qwen-32B",
+    /** Compact but capable */
+    mistral: "mistralai/Mistral-Small-24B-Instruct-2501",
+};
+//# sourceMappingURL=huggingface.js.map

package/dist/backends/huggingface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"huggingface.js","sourceRoot":"","sources":["../../src/backends/huggingface.ts"],"names":[],"mappings":"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"}

package/dist/backends/openai.d.ts

@@ -0,0 +1,24 @@
+import type { LLMBackend, ChatMessage, CompletionOptions, LLMResponse } from "../types.js";
+/**
+ * OpenAI-compatible LLM backend.
+ * Works with OpenAI, Venice, Groq, Ollama, agents.eco, or any compatible API.
+ */
+export declare class OpenAIBackend implements LLMBackend {
+    readonly name: string;
+    private apiKey;
+    private baseUrl;
+    private model;
+    constructor(config: {
+        name?: string;
+        apiKey: string;
+        baseUrl: string;
+        model: string;
+    });
+    complete(messages: ChatMessage[], options?: CompletionOptions): Promise<LLMResponse>;
+}
+export declare function openaiBackend(apiKey: string, model?: string): OpenAIBackend;
+export declare function veniceBackend(apiKey: string, model?: string): OpenAIBackend;
+export declare function groqBackend(apiKey: string, model?: string): OpenAIBackend;
+export declare function ollamaBackend(model?: string, baseUrl?: string): OpenAIBackend;
+export declare function agentsEcoBackend(apiKey: string, model?: string): OpenAIBackend;
+//# sourceMappingURL=openai.d.ts.map

package/dist/backends/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/backends/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3F;;;GAGG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf;IAOK,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;CA4D3F;AAID,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAiB,GAAG,aAAa,CAErF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,aAAa,CAEvF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAkC,GAAG,aAAa,CAEpG;AAED,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAmB,EAAE,OAAO,GAAE,MAAoC,GAAG,aAAa,CAEtH;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,aAAa,CAO1F"}