cocoon-ai-provider 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0
+
+- Initial release of `cocoon-ai-provider`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,135 @@
+# cocoon-ai-provider
+
+AI SDK v6 provider for [Cocoon](https://github.com/indie-cto/telegram-cocoon-ts-sdk).
+
+## Install
+
+```bash
+pnpm add cocoon-ai-provider ai
+```
+
+## Quick Start
+
+```ts
+import { cocoon } from 'cocoon-ai-provider';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: cocoon('Qwen/Qwen3-32B'),
+  prompt: 'Write a one-line welcome message.',
+});
+
+console.log(result.text);
+await cocoon.close();
+```
+
+## Streaming
+
+```ts
+import { cocoon } from 'cocoon-ai-provider';
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: cocoon('Qwen/Qwen3-32B'),
+  prompt: 'Write a short product tagline.',
+});
+
+for await (const textPart of result.textStream) {
+  process.stdout.write(textPart);
+}
+
+await cocoon.close();
+```
+
+## Runnable Example
+
+This repository includes a runnable end-to-end example at `examples/basic.mjs`.
+
+```bash
+COCOON_WALLET="your 24-word mnemonic" pnpm example:basic
+```
+
+Optional:
+
+- `COCOON_MODEL_ID` to override the model (default: `Qwen/Qwen3-32B`)
+- Any other Cocoon env vars described below
+
+## Custom Provider Instance
+
+You can pass an existing `Cocoon` client or let the provider build one from `clientOptions`.
+
+```ts
+import { createCocoon } from 'cocoon-ai-provider';
+
+const provider = createCocoon({
+  clientOptions: {
+    wallet: process.env.MNEMONIC!,
+    secretString: process.env.SECRET,
+    proxyUrl: process.env.PROXY_URL,
+  },
+  defaults: {
+    maxCoefficient: 1.2,
+    timeout: 30_000,
+  },
+});
+```
+
+## Provider Options
+
+Use call-level Cocoon options with `providerOptions.cocoon`:
+
+```ts
+import { generateText } from 'ai';
+import { cocoon } from 'cocoon-ai-provider';
+
+const result = await generateText({
+  model: cocoon('Qwen/Qwen3-32B'),
+  prompt: 'Summarize this in one sentence.',
+  providerOptions: {
+    cocoon: {
+      maxCoefficient: 1.1,
+      timeout: 20_000,
+    },
+  },
+});
+```
+
+Call-level `providerOptions.cocoon` override provider-level `defaults`.
+
+## Environment Variables
+
+When `createCocoon()` is called without `client` and without `clientOptions`, the provider builds a Cocoon client from env values.
+
+- `wallet`: `COCOON_WALLET` or `MNEMONIC` (required)
+- `secretString`: `COCOON_SECRET_STRING` or `SECRET`
+- `proxyUrl`: `COCOON_PROXY_URL` or `PROXY_URL`
+- `tonEndpoint`: `COCOON_TON_ENDPOINT` or `TON_ENDPOINT`
+- `tonV4Endpoint`: `COCOON_TON_V4_ENDPOINT` or `TON_V4_ENDPOINT`
+- `network`: `COCOON_NETWORK` (`mainnet` or `testnet`)
+- `timeout`: `COCOON_TIMEOUT` (positive number)
+- `useTls`: `COCOON_USE_TLS` (`true`/`false` or `1`/`0`)
+- `autoRegisterOnLongAuth`: `COCOON_AUTO_REGISTER_ON_LONG_AUTH` (`true`/`false` or `1`/`0`, default `false`)
+- `longAuthRegisterAmountTon`: `COCOON_LONG_AUTH_REGISTER_AMOUNT_TON`
+- TLS credential values: `COCOON_TLS_CERT` + `COCOON_TLS_KEY`
+- TLS credential files: `COCOON_TLS_CERT_PATH` + `COCOON_TLS_KEY_PATH`
+
+## Runtime and Limitations
+
+- Node.js `>=18` only.
+- v1 supports language-model generation and streaming only.
+- Tool calling is not supported.
+- Multimodal file input is not supported.
+- Embedding and image model methods intentionally throw `NoSuchModelError`.
+- Abort behavior is best-effort. Cocoon cancellation is limited by the underlying SDK.
+
+## Testing
+
+```bash
+pnpm test
+```
+
+Optional real-network integration tests:
+
+```bash
+pnpm test:integration
+```