tekimax-ts 0.1.6 → 1.0.0-beta.1

package/README.md

@@ -1,22 +1,12 @@
 <div align="center">
-  <img src="./public/logos/tekimax-logo-ScreenRGB-2.png" alt="Tekimax SDK Logo" width="200" />
-  <h1>Tekimax TypeScript SDK</h1>
-  <p><strong>Type-safe Tekimax Client for Node.js, Browser, and Edge.</strong></p>
+  <img src="https://raw.githubusercontent.com/TEKIMAX/tekimax-ts/main/apps/docs/public/tekimax-logo.png" alt="Tekimax SDK Logo" width="200" />
+  <h1>Tekimax TS</h1>
+  <p><strong>A type-safe, framework-agnostic AI SDK for building AI-powered apps.</strong></p>
 
-  [![npm version](https://img.shields.io/npm/v/tekimax-ts.svg)](https://www.npmjs.com/package/tekimax-ts)
-  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-</div>
-
-## 📖 Overview
-
-The **Tekimax TypeScript SDK** provides fully typed interfaces for the Tekimax API. Generated via [Kubb](https://kubb.dev/), it ensures your application stays in sync with the latest API definitions.
+[![npm version](https://img.shields.io/npm/v/tekimax-ts.svg)](https://www.npmjs.com/package/tekimax-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Features
-
-- **Full TypeScript Support**: strict typing for all API request/response bodies.
-- **Runtime Validation**: Optional Zod schemas for validating data at runtime.
-- **Universal**: Works in Node.js, React/Vite/Next.js, and Cloudflare Workers.
-- **Tree-Shakeable**: Import only what you need.
+</div>
 
 ## 📦 Installation
 
@@ -26,117 +16,190 @@ npm install tekimax-ts
 
 ## 💻 Usage
 
-### Importing Types
+### Standard Provider Pattern (Recommended)
+
+The SDK provides a `TekimaxProvider` that implements the standard `TekimaxAdapter` interface. This allows for interchangeable providers and consistent behavior.
 
 ```typescript
-import { 
-  UserMessageItemParam, 
-  CreateResponseBody 
-} from 'tekimax-ts';
-
-// Strongly typed message object
-const userMessage: UserMessageItemParam = {
-  type: 'message',
-  role: 'user',
-  content: [
-    {
-      type: 'input_text',
-      text: 'Explain quantum computing'
-    }
-  ]
-};
+import { TekimaxProvider } from 'tekimax-ts'
+
+const provider = new TekimaxProvider({
+  apiKey: process.env.TEKIMAX_API_KEY,
+})
+
+// Standard Chat
+const result = await provider.chat({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Explain quantum computing' }]
+})
+console.log(result.message.content)
+
+// Streaming Chat
+for await (const chunk of provider.chatStream({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Write a long poem' }]
+})) {
+  process.stdout.write(chunk.delta)
+}
 ```
 
-### formatting a Request
+### Agents & Tools
+
+The SDK supports high-level "Agentic" workflows where the model can autonomously call tools.
 
 ```typescript
-import { CreateResponseBody } from 'tekimax-ts';
-
-const requestPayload: CreateResponseBody = {
-  model: 'tekimax-1.0',
-  items: [userMessage],
-  stream: true
-};
-
-// Send to API with Authentication and Error Handling
-try {
-  const response = await fetch('https://api.tekimax.com/v1/generate', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': 'Bearer YOUR_API_KEY'
-    },
-    body: JSON.stringify(requestPayload)
-  });
-
-  if (!response.ok) {
-    throw new Error(`API Error: ${response.status} ${response.statusText}`);
+import { TekimaxProvider, generateText, tool } from 'tekimax-ts'
+
+const provider = new TekimaxProvider({ apiKey: '...' })
+
+const weatherTool = tool({
+  type: 'function', // optional, defaults to 'function' in helper
+  function: {
+    name: 'get_weather',
+    description: 'Get current weather',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: { type: 'string' }
+      },
+      required: ['location']
+    }
+  },
+  execute: async ({ location }) => {
+    return { temperature: 72, condition: 'Sunny' }
   }
+})
+
+const result = await generateText({
+  adapter: provider,
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'What is the weather in SF?' }],
+  tools: { weather: weatherTool },
+  maxSteps: 5 // Allow up to 5 steps (Model -> Tool -> Model loop)
+})
+
+console.log(result.text) 
+// "The weather in San Francisco is sunny with a temperature of 72°F."
+```
 
-  const data = await response.json();
-  console.log('Response:', data);
-  
-} catch (error) {
-  console.error('Failed to generate response:', error);
+```bash
+npm install react
+```
+
+Then import from `tekimax-ts/react`:
+
+```tsx
+import { TekimaxProvider } from 'tekimax-ts'
+import { useChat } from 'tekimax-ts/react'
+
+const provider = new TekimaxProvider({ apiKey: '...' })
+
+function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading, stop } = useChat({
+    adapter: provider,
+    model: 'gpt-4'
+  })
+
+  return (
+    <div>
+      {messages.map((m, i) => (
+        <div key={i}><strong>{m.role}:</strong> {m.content}</div>
+      ))}
+      
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} disabled={isLoading} />
+        <button type="submit" disabled={isLoading}>Send</button>
+        <button type="button" onClick={stop} disabled={!isLoading}>Stop</button>
+      </form>
+    </div>
+  )
 }
 ```
 
-### Advanced: Custom Configuration
+### Low-Level Client
 
-You can extend the generated types to build your own robust client wrapper:
+You can still use the direct `TekimaxClient` for raw API access if needed:
 
 ```typescript
-import { CreateResponseBody, RequiredItemParam } from 'tekimax-ts';
+import { TekimaxClient } from 'tekimax-ts'
 
-interface TekimaxConfig {
-    apiKey: string;
-    baseUrl?: string;
-}
+const client = new TekimaxClient({ apiKey: process.env.TEKIMAX_API_KEY })
+const response = await client.sendMessage('Hello!')
+console.log(response.text)
+```
 
-class TekimaxClient {
-    constructor(private config: TekimaxConfig) {}
+## 🧠 Motivation and Overview
 
-    async generate(body: CreateResponseBody) {
-        // Implementation...
-    }
-}
-```
+Modern LLM systems have converged on similar primitives: messages, function calls, tool usage, and multimodal inputs but each provider encodes them differently. **Tekimax** standardizes these concepts, enabling:
 
-## 🛠️ Development
+- **One spec, many providers**: Describe inputs/outputs once; run on OpenAI, Anthropic, Gemini, or local models.
+- **Composable agentic loops**: Unified streaming, tool invocation, and message orchestration.
+- **Easier evaluation and routing**: Compare providers, route requests, and log results through a shared schema.
+- **Blueprints for provider APIs**: Labs and model providers wanting to expose their APIs in a common format can easily do so.
 
-This SDK is generated from a centralized OpenAPI specification.
+## 🔑 Key Principles
 
-### Regenerate Code
+### Agentic Loop
 
-If the spec changes, run:
+All models, to some extent, exhibit agency: the ability to perceive input, reason, act through tools, and reflect on outcomes.
 
-```bash
-npm run generate
-```
+The **Tekimax Standard** at its core is designed to expose the power of this agentic loop to developers, making requests that allow the model to do multiple things and yield back a result, whether this is developer-hosted tool calls where control is yielded back to the user, or provider-hosted tools where control is held by the model provider until the model signals an exit criteria.
 
-### Build
+Tekimax defines a common pattern for defining control flow in the agent loop, a set of item definitions for developer-controlled tools, and pattern for defining provider and router-hosted tools.
 
-```bash
-npm run build
-```
+### Items → Items
 
-### Secure Container Build
+Items are the fundamental unit of context in Tekimax: they represent an atomic unit of model output, tool invocation, or reasoning state. Items are bidirectional, they can be provided as inputs to the model, or as outputs from the model.
 
-This SDK can be built inside a **Chainguard** container for maximum security and reproducibility.
+Each item type has a defined schema that binds it and contains properties specific to its unique purpose.
 
-```bash
-# Build using the hardened Chainguard Node.js image
-docker build -f Dockerfile -t tekimax-ts .
-```
+Tekimax defines a common set of items supported by a quorum of model providers, and defines how provider-specific item types can be defined.
+
+### Semantic Events
+
+Streaming is modeled as a series of semantic events, not raw text or object deltas.
+
+Events describe meaningful transitions. They are either state transitions (e.g., `response.in_progress`, `response.completed`) or they can represent a delta from a previous state (e.g., `response.output_item.added`, `response.output_text.delta`).
+
+Tekimax defines a common set of streaming events supported by a quorum of model providers, and defines how provider-specific streaming events can be defined.
+
+### State Machines
+
+Objects in Tekimax are state machines, that is, they can live in one of a finite number of states, such as `in_progress`, `completed`, or `failed`. The spec defines the set of valid states for each state machine in the API.
+
+## 🛡️ Security & Trust
+
+At **Tekimax**, we believe security is a feature, not an afterthought.
+
+- **Zero Vulnerabilities**: We enforce a strict **Zero CVE** policy. Our SDK is audited daily.
+- **Minimal Surface Area**: By optimizing our dependency tree, we identified and **removed 159 unnecessary packages**, drastically reducing the attack surface.
+- **Secured by Chainguard**: Our build pipeline and artifacts rely on [Chainguard Images](https://www.chainguard.dev/chainguard-images)—hardened, minimal container images designed to secure the software supply chain. Chainguard images are stripped of shells, package managers, and other unnecessary tools that attackers often exploit.
+
+Supply chain attacks on the Node.js/npm ecosystem are increasingly common. By building on Chainguard, we ensure that the Tekimax SDK meets the highest standards of integrity and safety for enterprise and production use.
+
+## Get Involved
+
+- We welcome issues and pull requests!
+- Participate in **GitHub Discussions**.
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions.
+
+## Partners
+
+We're looking for Tekimax Partners to join our mission! Partner with us to push the boundaries of Tekimax and build amazing things together.
+
+[LET'S CHAT](mailto:info@tekimax.com?subject=Tekimax%20Partnership)
 
-### 🛡️ Security Verification
+## Code of Conduct
 
-*   **Scanner**: Trivy (v0.69.0)
-*   **Date**: 2026-01-31
-*   **Result**: ✅ **0 Vulnerabilities** (Clean)
-*   **Base Image**: `cgr.dev/chainguard/node:latest-dev`
+## Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
 
----
 <div align="center">
+  <p>
+    <strong>Secured by <a href="https://www.chainguard.dev">Chainguard</a></strong><br>
+    Zero-CVE Images for a Safe Supply Chain
+  </p>
+  <p>
+    Built on the <a href="https://openresponses.org">OpenResponses Standard</a> • Generated with <a href="https://kubb.dev">Kubb</a>
+  </p>
   <sub>Built with ❤️ by the Tekimax Team</sub>
 </div>

package/dist/adapter-BtbeHotF.d.cts

@@ -0,0 +1,81 @@
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+interface Tool<T = any> extends ToolDefinition {
+    execute: (args: T) => Promise<unknown>;
+}
+interface GenerateTextResult {
+    text: string;
+    toolCalls: Array<ToolCall>;
+    toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'error' | 'unknown';
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    warnings?: Array<string>;
+}
+interface Message {
+    role: MessageRole;
+    content: string | null;
+    toolCalls?: Array<ToolCall>;
+    toolCallId?: string;
+    name?: string;
+}
+interface ChatOptions {
+    model: string;
+    messages: Array<Message>;
+    tools?: Array<ToolDefinition>;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    message: Message;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface StreamChunk {
+    delta: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+
+interface TekimaxAdapter {
+    name: string;
+    /**
+     * Send a chat completion request.
+     */
+    chat: (options: ChatOptions) => Promise<ChatResult>;
+    /**
+     * Stream a chat completion.
+     */
+    chatStream: (options: ChatOptions) => AsyncIterable<StreamChunk>;
+}
+
+export type { ChatOptions as C, GenerateTextResult as G, Message as M, StreamChunk as S, TekimaxAdapter as T, ChatResult as a, Tool as b, MessageRole as c, ToolCall as d, ToolDefinition as e };

package/dist/adapter-BtbeHotF.d.ts

@@ -0,0 +1,81 @@
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+interface Tool<T = any> extends ToolDefinition {
+    execute: (args: T) => Promise<unknown>;
+}
+interface GenerateTextResult {
+    text: string;
+    toolCalls: Array<ToolCall>;
+    toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'error' | 'unknown';
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    warnings?: Array<string>;
+}
+interface Message {
+    role: MessageRole;
+    content: string | null;
+    toolCalls?: Array<ToolCall>;
+    toolCallId?: string;
+    name?: string;
+}
+interface ChatOptions {
+    model: string;
+    messages: Array<Message>;
+    tools?: Array<ToolDefinition>;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    message: Message;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface StreamChunk {
+    delta: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+
+interface TekimaxAdapter {
+    name: string;
+    /**
+     * Send a chat completion request.
+     */
+    chat: (options: ChatOptions) => Promise<ChatResult>;
+    /**
+     * Stream a chat completion.
+     */
+    chatStream: (options: ChatOptions) => AsyncIterable<StreamChunk>;
+}
+
+export type { ChatOptions as C, GenerateTextResult as G, Message as M, StreamChunk as S, TekimaxAdapter as T, ChatResult as a, Tool as b, MessageRole as c, ToolCall as d, ToolDefinition as e };

package/dist/adapter-CMu9Gvvm.d.cts

@@ -0,0 +1,81 @@
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+interface Tool<T = any> extends ToolDefinition {
+    execute: (args: T) => Promise<unknown>;
+}
+interface GenerateTextResult {
+    text: string;
+    toolCalls: Array<ToolCall>;
+    toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'error' | 'unknown';
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    warnings?: string[];
+}
+interface Message {
+    role: MessageRole;
+    content: string | null;
+    toolCalls?: Array<ToolCall>;
+    toolCallId?: string;
+    name?: string;
+}
+interface ChatOptions {
+    model: string;
+    messages: Array<Message>;
+    tools?: Array<ToolDefinition>;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    message: Message;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface StreamChunk {
+    delta: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+
+interface TekimaxAdapter {
+    name: string;
+    /**
+     * Send a chat completion request.
+     */
+    chat: (options: ChatOptions) => Promise<ChatResult>;
+    /**
+     * Stream a chat completion.
+     */
+    chatStream: (options: ChatOptions) => AsyncIterable<StreamChunk>;
+}
+
+export type { ChatOptions as C, GenerateTextResult as G, Message as M, StreamChunk as S, TekimaxAdapter as T, ChatResult as a, MessageRole as b, Tool as c, ToolCall as d, ToolDefinition as e };

package/dist/adapter-CMu9Gvvm.d.ts

@@ -0,0 +1,81 @@
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+interface Tool<T = any> extends ToolDefinition {
+    execute: (args: T) => Promise<unknown>;
+}
+interface GenerateTextResult {
+    text: string;
+    toolCalls: Array<ToolCall>;
+    toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'error' | 'unknown';
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    warnings?: string[];
+}
+interface Message {
+    role: MessageRole;
+    content: string | null;
+    toolCalls?: Array<ToolCall>;
+    toolCallId?: string;
+    name?: string;
+}
+interface ChatOptions {
+    model: string;
+    messages: Array<Message>;
+    tools?: Array<ToolDefinition>;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    message: Message;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface StreamChunk {
+    delta: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+
+interface TekimaxAdapter {
+    name: string;
+    /**
+     * Send a chat completion request.
+     */
+    chat: (options: ChatOptions) => Promise<ChatResult>;
+    /**
+     * Stream a chat completion.
+     */
+    chatStream: (options: ChatOptions) => AsyncIterable<StreamChunk>;
+}
+
+export type { ChatOptions as C, GenerateTextResult as G, Message as M, StreamChunk as S, TekimaxAdapter as T, ChatResult as a, MessageRole as b, Tool as c, ToolCall as d, ToolDefinition as e };

package/dist/adapter-DeUJcFAn.d.cts

@@ -0,0 +1,43 @@
+type MessageRole = 'system' | 'user' | 'assistant';
+interface Message {
+    role: MessageRole;
+    content: string;
+}
+interface ChatOptions {
+    model: string;
+    messages: Array<Message>;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    message: Message;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface StreamChunk {
+    delta: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+
+interface TekimaxAdapter {
+    name: string;
+    /**
+     * Send a chat completion request.
+     */
+    chat: (options: ChatOptions) => Promise<ChatResult>;
+    /**
+     * Stream a chat completion.
+     */
+    chatStream: (options: ChatOptions) => AsyncIterable<StreamChunk>;
+}
+
+export type { ChatOptions as C, Message as M, StreamChunk as S, TekimaxAdapter as T, ChatResult as a, MessageRole as b };