tekimax-ts 0.2.3 → 0.2.4

package/README.md

@@ -1,28 +1,52 @@
 <div align="center">
-  <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>The Universal Standard.</strong></p>
-  <p>A type-safe, framework-agnostic AI SDK for building AI-powered apps.</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)
+  <img src="https://raw.githubusercontent.com/TEKIMAX/tekimax-ts/main/apps/docs/public/tekimax-logo.png" alt="Tekimax SDK Logo" width="120" />
+  <h1>Tekimax SDK</h1>
+  <p><strong>The Universal Standard</strong></p>
+  
+  <p>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
+    <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0-3178C6.svg" alt="TypeScript"></a>
+    <a href="https://tekimax.com"><img src="https://img.shields.io/badge/Standard-Tekimax-000000.svg" alt="Standard"></a>
+    <a href="https://www.npmjs.com/package/tekimax-ts"><img src="https://img.shields.io/npm/v/tekimax-ts.svg" alt="NPM Version"></a>
+    <a href="https://packagephobia.com/result?p=tekimax-ts"><img src="https://packagephobia.com/badge?p=tekimax-ts" alt="Bundle Size"></a>
+  </p>
+  
+  <p>
+    Integrate <strong>OpenAI</strong>, <strong>Anthropic</strong>, <strong>Gemini</strong>, <strong>Ollama</strong>, <strong>Grok</strong>, and <strong>OpenRouter</strong> with a single, type-safe API.
+  </p>
 
+  <div>
+    <img src="https://img.shields.io/badge/OpenAI-412991?style=for-the-badge&logo=openai&logoColor=white" alt="OpenAI" />
+    <img src="https://img.shields.io/badge/Anthropic-D06940?style=for-the-badge&logo=anthropic&logoColor=white" alt="Anthropic" />
+    <img src="https://img.shields.io/badge/Gemini-8E75B2?style=for-the-badge&logo=google%20gemini&logoColor=white" alt="Gemini" />
+    <img src="https://img.shields.io/badge/Ollama-000000?style=for-the-badge&logo=ollama&logoColor=white" alt="Ollama" />
+    <img src="https://img.shields.io/badge/Grok-000000?style=for-the-badge&logo=x&logoColor=white" alt="Grok" />
+    <img src="https://img.shields.io/badge/OpenRouter-6366F1?style=for-the-badge&logo=openai&logoColor=white" alt="OpenRouter" />
+  </div>
 </div>
 
-## 📦 Installation
+---
 
-```bash
-npm install tekimax-ts
-```
+## 🚀 The Universal Standard
 
-## 🌟 Features
+The **Tekimax SDK** solves the fragmentation of AI APIs. Instead of rewriting your integration code for every provider (handling different request formats, streaming implementations, and error types), you use **one standard interface**.
 
-- **Universal API**: One interface for all providers. Switch from OpenAI to Ollama with a single config change.
-- **Strict Modality Type Safety**: End-to-end TypeScript support. Strong capability interfaces ensure compile-time safety (e.g., your code won't compile if you call `.images.generate()` on a provider missing the `ImageGenerationCapability`). Zod schemas for runtime validation.
-- **Zero Latency**: Lightweight adapter pattern with zero runtime overhead.
-- **Zero CVEs**: Hardened supply chain using Chainguard images.
+- **Write Once, Run Anywhere**: Switch between OpenAI (Cloud) and Ollama (Local) with a single line of config.
+- **Type-Safe**: Full TypeScript support with Zod validation for inputs and outputs.
+- **Multi-Modal**: Text, images, audio, video, and **embeddings** through a unified namespace API.
+- **OpenResponses Catalog**: Fuses `models.dev` metadata into standard `ModelDefinition` objects for reasoning, modalities, and token limits.
+- **Middleware Plugins**: Built-in architecture for Security (`PIIFilterPlugin`), Scalability (`MaxContextOverflowPlugin`), and Telemetry (`LoggerPlugin`).
+- **React Ready**: Includes a `useChat` hook for instant UI integration, complete with SSE streaming.
 - **Redis Adapter** _(optional)_: Response caching, rate limiting, token budgets, and session storage with any Redis client.
 
+
+## 💻 Installation
+
+```bash
+# Install core and your desired adapters
+npm install tekimax-ts
+```
+
 ## 💻 Usage
 
 ### 1. Initialize the Client
@@ -52,60 +76,6 @@ const claude = new Tekimax({
 const local = new Tekimax({
     provider: new OllamaProvider({ baseUrl: 'http://localhost:11434' })
 })
-
-// Custom Model Proxies (e.g. Internal API gateways)
-const proxyClient = new Tekimax({
-    provider: new OpenAIProvider({ 
-        apiKey: process.env.CUSTOM_PROXY_KEY,
-        baseURL: 'https://api.my-custom-proxy.internal/v1' 
-    })
-})
-
-### Streaming
-
-Tekimax-TS uses standard Javascript Async Iterables for real-time streaming:
-
-```typescript
-const stream = await client.text.generateStream({
-  model: "gpt-4o",
-  messages: [{ role: "user", content: "Tell me a story" }]
-})
-
-for await (const chunk of stream) {
-  process.stdout.write(chunk.delta)
-}
-```
-
-## 🔌 Plugin Architecture (Lifecycle Hooks)
-
-The SDK provides a robust middleware architecture via `plugins`. You can snap in pre-built plugins for Security, Scalability, and Telemetry, or build your own.
-
-```typescript
-import { Tekimax, OpenAIProvider, PIIFilterPlugin, LoggerPlugin, MaxContextOverflowPlugin } from 'tekimax-ts'
-
-const client = new Tekimax({
-    provider: new OpenAIProvider({ apiKey: 'sk-...' }),
-    plugins: [
-        new LoggerPlugin(), // Telemetry
-        new PIIFilterPlugin(), // Security: Redacts emails and SSNs
-        new MaxContextOverflowPlugin(15) // Scalability: Prevents context bloat in long loops
-    ]
-})
-```
-
-### Building Custom Plugins
-Implement the `TekimaxPlugin` interface to hook into the request/response lifecycle:
-
-```typescript
-export interface TekimaxPlugin {
-    name: string
-    onInit?: (client: Tekimax) => void
-    beforeRequest?: (context: PluginContext) => Promise<void | PluginContext>
-    afterResponse?: (context: PluginContext, result: ChatResult) => Promise<void>
-    onStreamChunk?: (context: PluginContext, chunk: StreamChunk) => void
-    beforeToolExecute?: (toolName: string, args: unknown) => Promise<void>
-    afterToolExecute?: (toolName: string, result: unknown) => Promise<void>
-}
 ```
 
 ### 2. Multi-Modal Interfaces
@@ -160,109 +130,95 @@ const analysis = await client.videos.analyze({
 })
 ```
 
-## 📚 Documentation
-
-For full documentation, guides, and API references, visit **[docs.tekimax.com](https://docs.tekimax.com)**.
-
-## 🧠 Motivation
-
-
-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:
-
-- **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.
-
-## 🔑 Key Principles
-
-### Agentic Loop
-
-All models, to some extent, exhibit agency: the ability to perceive input, reason, act through tools, and reflect on outcomes.
+#### Embeddings
 
-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.
-
-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.
-
-### Items → Items
-
-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.
-
-Each item type has a defined schema that binds it and contains properties specific to its unique purpose.
+```typescript
+const vectors = await client.text.embed({
+    model: 'text-embedding-3-small',
+    input: ['Hello world', 'Tekimax SDK is awesome']
+})
+console.log(vectors.embeddings)
+```
 
-Tekimax defines a common set of items supported by a quorum of model providers, and defines how provider-specific item types can be defined.
+### 3. Cross-Provider Model Catalog
 
-### Semantic Events
+The SDK strictly implements the **OpenResponses** schema, optionally fusing metadata from `models.dev` so your application always knows what capabilities the active provider supports.
 
-Streaming is modeled as a series of semantic events, not raw text or object deltas.
+```typescript
+// Returns standard ModelDefinition[] populated with reasoning levels, modal limits, and costs
+const models = await client.provider.getModels?.() 
 
-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`).
+if (models) {
+    console.log(models.find(m => m.id === 'gpt-4o')?.modalities.input) // ['text', 'image', 'audio', 'video']
+}
+```
 
-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.
+## 🏗️ Monorepo Structure
 
-### State Machines
+This repository is managed as a **Turborepo** monorepo.
 
-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.
+- **`apps/docs`**: Documentation site (Next.js + Fumadocs).
+- **`packages/*`**: Core SDK and Provider Adapters.
+- **`tekimax-cli`**: Developer tools for Tekimax.
 
-## 🛡️ Security & Trust
+### Commands
 
-At **Tekimax**, we believe security is a feature, not an afterthought.
+```bash
+# Build all packages
+npx turbo build
 
-- **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.
+# Run tests
+npx turbo test
 
-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.
+# Start Docs Site
+npx turbo dev --filter=docs
+```
 
 ## ⚡ Optional Redis Adapter
 
+No extra dependency — bring your own `ioredis`, `@upstash/redis`, or `node-redis`:
+
 ```typescript
 import { ResponseCache, RateLimiter, TokenBudget, SessionStore } from 'tekimax-ts'
 import Redis from 'ioredis'
 
 const redis = new Redis(process.env.REDIS_URL)
-const cache   = new ResponseCache(redis, { ttl: 3600 })       // Cache responses
-const limiter = new RateLimiter(redis, { maxRequests: 60 })    // Rate limit
-const budget  = new TokenBudget(redis, { maxTokens: 100_000 }) // Token budget
-const sessions = new SessionStore(redis, { ttl: 1800 })        // Sessions
+
+// Cache AI responses (avoid repeat API costs)
+const cache = new ResponseCache(redis, { ttl: 3600 })
+
+// Enforce rate limits per provider
+const limiter = new RateLimiter(redis, { maxRequests: 60, windowSeconds: 60 })
+
+// Track daily token spend
+const budget = new TokenBudget(redis, { maxTokens: 100_000, periodSeconds: 86400 })
+
+// Conversation state for serverless
+const sessions = new SessionStore(redis, { ttl: 1800 })
 ```
 
 ## 🗺️ Roadmap
 
 | Feature | Description | Status |
 |---------|-------------|--------|
-| **Batch API** | OpenAI's Batch API for 50% cost reduction on large jobs. Queue thousands of requests and retrieve results asynchronously. | 🔜 Planned |
-| **Edge Runtime** | Cloudflare Workers / Deno support. Current `Buffer` usage blocks edge compatibility — will be replaced with `Uint8Array` and Web Streams. | 🔜 Planned |
-| **Assistants / Threads** | Stateful conversation management with persistence. Create threads, append messages, and resume conversations across sessions. | 🔜 Planned |
-| **Fine-tuning API** | Programmatic fine-tuning via OpenAI and Gemini APIs. Upload training data, launch jobs, and deploy custom models through a unified interface. | 🔜 Planned |
-| **Observability** | OpenTelemetry spans for every provider call — latency, tokens, cost, and error rate. | 🔜 Planned |
-| **Redis Adapter** | Optional response caching, rate limiting, token budget tracking, and session storage with any Redis-compatible client. | ✅ Shipped |
+| **Middleware Plugins** | Pre-built and custom lifecycle hooks for Security, Telemetry, and Scalability. | ✅ Shipped |
+| **OpenResponses Catalog** | Provider abstraction parsing `models.dev` metadata for token limits, reasoning capabilities, and allowed modalities. | ✅ Shipped |
+| **Real-time SSE Streaming** | Native SDK token streaming, `StreamChunk` event typing, and full React hooks support (`useChat`). | ✅ Shipped |
+| **Redis Adapter** | Optional response caching, rate limiting, token budget tracking, and session storage with any Redis client. | ✅ Shipped |
+| **Observability** | Telemetry and tracing via `plugins` architecture. | ✅ Shipped |
+| **Batch API** | Queue thousands of requests and retrieve results asynchronously. | 🔜 Planned |
+| **Edge Runtime** | Cloudflare Workers / Deno support. | 🔜 Planned |
+| **Assistants / Threads** | Stateful conversation management with persistence. | 🔜 Planned |
+| **Fine-tuning API** | Programmatic fine-tuning via internal and integrated APIs. | 🔜 Planned |
 
 > **Want to help?** Pick a feature and open a PR, or join the discussion in [GitHub Issues](https://github.com/TEKIMAX/tekimax-ts/issues).
 
-## Get Involved
+## 💖 Support
 
-- We welcome issues and pull requests!
-- Participate in **GitHub Discussions**.
-- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions.
+Tekimax is open source. If you find it valuable, please consider [becoming a sponsor](https://github.com/sponsors/TEKIMAX) to support long-term maintenance.
 
-## 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)
-
-## Code of Conduct
-
-## 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>
+  <p>Built with ❤️ by the Tekimax Team</p>
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tekimax-ts",
-    "version": "0.2.3",
+    "version": "0.2.4",
     "type": "module",
     "description": "A type-safe, framework-agnostic AI SDK for building AI-powered apps.",
     "homepage": "https://tekimax.com",