@standardagents/groq 0.0.1-dev.ffffff → 0.14.0

package/LICENSE.txt

@@ -0,0 +1,48 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 FormKit Inc. All Rights Reserved.
+
+UNLICENSED - DO NOT USE
+
+This software and associated documentation files (the "Software") are the sole
+and exclusive property of FormKit Inc. ("FormKit").
+
+USE RESTRICTIONS
+
+The Software is UNLICENSED and proprietary. NO PERMISSION is granted to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, or to permit persons to whom the Software is furnished to do so,
+under any circumstances, without prior written authorization from FormKit Inc.
+
+UNAUTHORIZED USE PROHIBITED
+
+Any use of this Software without a valid, written license agreement signed by
+authorized officers of FormKit Inc. is strictly prohibited and constitutes
+unauthorized use and infringement of FormKit's intellectual property rights.
+
+LICENSING INQUIRIES
+
+Organizations interested in licensing this Software should contact:
+enterprise@formkit.com
+
+A written license agreement must be executed before any use of this Software
+is authorized.
+
+NO WARRANTY
+
+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
+FORMKIT INC. 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.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with the laws
+of the jurisdiction in which FormKit Inc. is incorporated, without regard to
+its conflict of law provisions.
+
+FormKit Inc.
+https://formkit.com
+enterprise@formkit.com

package/README.md

@@ -1,7 +1,143 @@
 # @standardagents/groq
 
-Stub prerelease package for Standard Agents Groq provider publishing setup.
+Groq provider for Standard Agents.
 
-Current bootstrap version: `0.0.1-dev.ffffff`
+This package wraps Groq's Chat Completions API behind the Standard Agents provider interface. It supports:
 
-This package will be wired into the normal monorepo release flow after trusted publishing is configured.
+- model discovery
+- Standard Agents message transformation to Groq chat payloads
+- streaming and non-streaming generation
+- local function tool calling on Groq models that support it
+- reasoning controls on supported reasoning models
+- Groq usage and cost calculation
+
+## Install
+
+```bash
+npm install @standardagents/groq @standardagents/spec
+```
+
+## Usage
+
+```ts
+import { groq } from '@standardagents/groq';
+
+const provider = groq({
+  apiKey: process.env.GROQ_API_KEY!,
+});
+
+const result = await provider.generate({
+  model: 'llama-3.3-70b-versatile',
+  messages: [
+    { role: 'user', content: 'Give me three short product name ideas.' },
+  ],
+});
+
+console.log(result.content);
+console.log(result.usage?.cost);
+```
+
+## Factory
+
+The package exports:
+
+- `groq(config)` - provider factory
+- `GroqProvider` - provider class
+- `groqProviderOptions` - Zod schema for provider-specific options
+
+Factory config:
+
+```ts
+type ProviderFactoryConfig = {
+  apiKey: string;
+  baseUrl?: string;
+  timeout?: number;
+};
+```
+
+## Supported Features
+
+Feature support is model-specific.
+
+Typical supported capabilities include:
+
+- streaming text generation
+- JSON mode on supported chat models
+- local function tool calling on supported models
+- reasoning controls on supported reasoning models
+
+Inspect the live model list and capabilities:
+
+```ts
+const models = await provider.getModels?.();
+const capabilities = await provider.getModelCapabilities?.('openai/gpt-oss-120b');
+```
+
+## Tool Calling Notes
+
+This package only sends Standard Agents local tools to Groq models that support local/custom tool calling.
+
+Important edge case:
+
+- `compound-beta` and `compound-beta-mini` support Groq built-in/server-side tools, but not Standard Agents custom function tools
+- this provider therefore strips local tools for Compound models instead of forwarding unsupported tool definitions
+
+If you need Standard Agents function tools, use one of the normal Groq function-calling models instead of Compound.
+
+## Reasoning Controls
+
+The provider only sends `reasoning_format`, `include_reasoning`, and `reasoning_effort` when the target model is known to support Groq reasoning controls.
+
+This avoids hard failures like:
+
+- ``reasoning_format is not supported with this model``
+
+## Provider Options
+
+Common Groq-specific provider options:
+
+- `citation_options`
+- `disable_tool_validation`
+- `include_reasoning`
+- `reasoning_effort`
+- `reasoning_format`
+- `service_tier`
+- `search_settings`
+- `compound_custom`
+- `documents`
+
+Example:
+
+```ts
+const result = await provider.generate({
+  model: 'openai/gpt-oss-120b',
+  messages: [{ role: 'user', content: 'Solve this carefully.' }],
+  providerOptions: {
+    reasoning_format: 'parsed',
+    reasoning_effort: 'high',
+    service_tier: 'performance',
+  },
+});
+```
+
+## Icons
+
+`getIcon(modelId?)` returns either the Groq provider icon or a model-lab icon derived from the model identifier when possible, such as:
+
+- `openai/gpt-oss-120b` -> OpenAI icon
+- `qwen/qwen3-32b` -> Qwen icon
+- `llama-*` -> Meta icon
+- `gemma*` -> Google icon
+
+## Debugging
+
+Use `inspectRequest()` to see the final Groq-native request body after model-specific transforms are applied:
+
+```ts
+const inspected = await provider.inspectRequest?.({
+  model: 'llama-3.1-8b-instant',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+
+console.log(inspected?.body);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/groq",
-  "version": "0.0.1-dev.ffffff",
+  "version": "0.14.0",
   "private": false,
   "publishConfig": {
     "access": "restricted",
@@ -20,13 +20,6 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "cd ../.. && vitest --dir packages/groq",
-    "test:run": "cd ../.. && vitest run --dir packages/groq"
-  },
   "dependencies": {
     "groq-sdk": "^1.1.2",
     "zod": "^4.3.5"
@@ -35,9 +28,9 @@
     "@standardagents/spec": "^0.10.0"
   },
   "devDependencies": {
-    "@standardagents/spec": "workspace:*",
     "tsup": "^8.3.5",
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.0",
+    "@standardagents/spec": "0.14.0"
   },
   "keywords": [
     "standardagents",
@@ -47,5 +40,12 @@
     "llm"
   ],
   "author": "FormKit Inc.",
-  "license": "UNLICENSED"
-}
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "cd ../.. && vitest --dir packages/groq",
+    "test:run": "cd ../.. && vitest run --dir packages/groq"
+  }
+}