tekimax-ts 0.2.0 → 0.2.3

package/README.md

@@ -18,11 +18,10 @@ npm install tekimax-ts
 ## 🌟 Features
 
 - **Universal API**: One interface for all providers. Switch from OpenAI to Ollama with a single config change.
-- **Type Safety**: End-to-end TypeScript support. Zod schemas for runtime validation.
+- **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.
 - **Redis Adapter** _(optional)_: Response caching, rate limiting, token budgets, and session storage with any Redis client.
-- **Convex Integration**: Provision and manage [Convex](https://convex.dev) projects, push schemas, set env vars, and deploy — all from code.
 
 ## 💻 Usage
 
@@ -53,6 +52,60 @@ 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
@@ -183,7 +236,6 @@ const sessions = new SessionStore(redis, { ttl: 1800 })        // Sessions
 | **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 |
-| **Convex Integration** | Provision and manage [Convex](https://convex.dev) projects directly via the SDK. Create projects, push schemas, set env vars, and deploy. | ✅ Shipped |
 | **Redis Adapter** | Optional response caching, rate limiting, token budget tracking, and session storage with any Redis-compatible client. | ✅ Shipped |
 
 > **Want to help?** Pick a feature and open a PR, or join the discussion in [GitHub Issues](https://github.com/TEKIMAX/tekimax-ts/issues).