heyi 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Tobias Reich
+
+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,108 @@
+# heyi
+
+> CLI tool to execute AI prompts with flexible output formatting
+
+Execute AI prompts directly from your terminal with support for multiple models and structured output formats using OpenRouter and the Vercel AI SDK.
+
+## Install
+
+```sh
+npm install heyi -g
+```
+
+## Usage
+
+### CLI
+
+```sh
+heyi [prompt] [options]
+```
+
+#### Options
+
+- `-m, --model <model>` - AI model to use (default: `openai/gpt-4o-mini`)
+- `-f, --format <format>` - Output format: `string`, `number`, `object`, `array` (default: `string`)
+- `-s, --schema <schema>` - Zod schema for object/array format (required when format is `object` or `array`)
+- `--file <path>` - Read content from file and include as context
+- `-h, --help` - Display help information
+- `-V, --version` - Display version number
+
+#### Environment Variables
+
+- `API_KEY` - OpenRouter API key (required, can be set via environment or `.env` file)
+- `MODEL` - Default AI model to use (optional, can be overridden with `--model` flag)
+
+### Examples
+
+```sh
+# Simple text prompt
+heyi "What is the capital of France?"
+
+# Use a different model
+heyi "Explain quantum computing" --model google/gemini-2.0-flash-exp
+
+# Get structured output as array of strings
+heyi "List 5 programming languages" --format array --schema "z.string()"
+
+# Get structured output as array of objects
+heyi "List 3 countries with their capitals" --format array --schema "z.object({name:z.string(),capital:z.string()})"
+
+# Get structured output as single object
+heyi "Analyze: revenue 100k, costs 60k" --format object --schema "z.object({revenue:z.number(),costs:z.number()})"
+
+# Complex nested schema
+heyi "Analyze top 3 tech companies" --format array --schema "z.object({name:z.string(),founded:z.number(),products:z.array(z.string())})"
+
+# Set default model via environment variable
+MODEL=perplexity/sonar heyi "Explain AI"
+
+# Set API key via environment variable
+API_KEY=your-key heyi "Hello, AI!"
+
+# Input from file as context
+heyi "Summarize this content" --file input.txt
+
+# Input from stdin
+cat article.md | heyi "Extract all URLs mentioned"
+echo "Analyze this text" | heyi
+```
+
+## Output Formats
+
+- **string** (default): Plain text response from the AI model
+- **number**: Numeric response from the AI model
+- **object**: Single JSON object with structured data (requires `--schema` flag)
+- **array**: JSON array with structured data (requires `--schema` flag)
+
+The tool uses Zod schemas to ensure the AI model returns data in the requested format. When using `object` or `array` formats, you must provide a Zod schema string via the `--schema` flag.
+
+### Schema Examples
+
+- String array: `--format array --schema "z.string()"`
+- URL array: `--format array --schema "z.url()"` (not supported by all models)
+- Object array: `--format array --schema "z.object({name:z.string(),age:z.number()})"`
+- Single object: `--format object --schema "z.object({total:z.number(),items:z.array(z.string())})"`
+
+## Development
+
+```sh
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Lint and format code
+npm run format
+
+# Run the CLI in development
+npm start -- "Your prompt here"
+
+# Or run directly
+./bin/index.js "Your prompt here"
+```
+
+## Related
+
+- [Vercel AI SDK](https://sdk.vercel.ai/) - Toolkit for building AI applications
+- [OpenRouter](https://openrouter.ai/) - Unified API for LLMs

package/bin/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import pkg from '../package.json' with { type: 'json' }
+import { executePrompt } from '../src/index.js'
+import { hasStdinData, readFileContent, readStdin } from '../src/utils/input.js'
+
+const DEFAULT_MODEL = 'openai/gpt-4o-mini'
+
+const program = new Command()
+
+const helpText = `
+Examples:
+  $ heyi "What is the capital of France?"
+  $ heyi "What is quantum computing?" --model google/gemini-2.5-pro
+
+  # Different output formats
+  $ heyi "List 5 programming languages" --format array --schema "z.string()"
+  $ heyi "Analyze this data" --format object --schema "z.object({revenue:z.number(),costs:z.number()})"
+  $ heyi "List 3 countries" --format array --schema "z.object({name:z.string(),capital:z.string()})"
+
+  # Environment variables
+  $ MODEL=perplexity/sonar heyi "Explain AI"
+  $ API_KEY=your-key heyi "Hello, AI!"
+
+  # Input from stdin or file
+  $ heyi "Summarize this content" --file input.txt
+  $ cat prompt.txt | heyi
+`
+
+const action = async (prompt, options) => {
+  try {
+    // Validate that schema is provided for object/array formats
+    if ((options.format === 'object' || options.format === 'array') && !options.schema) {
+      throw new Error(`--schema or -s is required when format is '${options.format}'`)
+    }
+
+    // Handle file content as context
+    let fileContent = null
+    if (options.file) {
+      fileContent = await readFileContent(options.file)
+    }
+
+    // Handle stdin input
+    let stdinContent = null
+    if (hasStdinData()) {
+      stdinContent = await readStdin()
+    }
+
+    // Validate that we have a prompt
+    if (!prompt && !stdinContent) {
+      throw new Error('A prompt is required. Provide it as an argument or via stdin.')
+    }
+
+    // Build the final prompt
+    let finalPrompt = prompt ?? stdinContent
+    if (fileContent) {
+      finalPrompt = `${finalPrompt}\n\nContext from file:\n${fileContent}`
+    }
+
+    const result = await executePrompt(finalPrompt, {
+      model: options.model,
+      format: options.format,
+      schema: options.schema,
+    })
+
+    console.log(result)
+  } catch (error) {
+    const relevantFields = Object.keys(error).filter((key) => ['stack', 'isRetryable', 'data'].includes(key) === false)
+    const relevantError = Object.fromEntries(relevantFields.map((key) => [key, error[key]]))
+    console.error(relevantError)
+
+    process.exit(1)
+  }
+}
+
+program
+  .name(pkg.name)
+  .description(pkg.description)
+  .version(pkg.version)
+  .argument('[prompt]', 'The AI prompt to execute (optional when using stdin)')
+  .option('-m, --model <model>', 'AI model to use', process.env.MODEL ?? DEFAULT_MODEL)
+  .option('-f, --format <format>', 'Output format: string, number, object, array', 'string')
+  .option('-s, --schema <schema>', 'Zod schema for object/array format (required when format is object or array)')
+  .option('--file <path>', 'Read content from file and include as context')
+  .addHelpText('after', helpText)
+  .action(action)
+  .parse()

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "heyi",
+  "version": "1.0.0",
+  "description": "CLI tool to execute AI prompts with flexible output formatting",
+  "keywords": [
+    "ai",
+    "cli",
+    "openrouter",
+    "llm",
+    "prompt"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": "./bin/index.js",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "eslint": "eslint \"**/*.js\"",
+    "format": "npm run eslint -- --fix && npm run prettier -- --write",
+    "lint": "npm run eslint && npm run prettier -- --check",
+    "prettier": "prettier --ignore-path .gitignore \"**/*.{js,json,md,yml}\"",
+    "start": "./bin/index.js",
+    "test": "npm run lint"
+  },
+  "dependencies": {
+    "@openrouter/ai-sdk-provider": "^1.5.3",
+    "ai": "^5.0.113",
+    "commander": "^14.0.2",
+    "dotenv": "^14.3.2",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@electerious/eslint-config": "^5.2.1",
+    "@electerious/prettier-config": "^4.0.0",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "authors": [
+    "Tobias Reich <tobias@electerious.com>"
+  ]
+}

package/src/index.js

@@ -0,0 +1,51 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+import { generateObject } from 'ai'
+import { config } from 'dotenv'
+import { getFormatSchema } from './utils/schema.js'
+
+// Load environment variables from .env file
+config()
+
+/**
+ * Execute an AI prompt with the specified model and format.
+ *
+ * @param {string} prompt - The user's prompt
+ * @param {object} options - Configuration options
+ * @param {string} options.model - The AI model to use
+ * @param {string} options.format - The output format (string, number, object, array)
+ * @param {string} options.schema - The Zod schema string for object/array format
+ * @returns {Promise<string>} The formatted AI response
+ */
+export const executePrompt = async (prompt, options = {}) => {
+  const { model, format = 'string', schema } = options
+
+  const apiKey = process.env.API_KEY
+  if (!apiKey) {
+    throw new Error('API_KEY environment variable is required. Set it via environment or .env file.')
+  }
+
+  const openrouter = createOpenRouter({
+    apiKey,
+  })
+
+  const zodSchema = getFormatSchema(format, schema)
+  const { object } = await generateObject({
+    model: openrouter(model),
+    prompt,
+    schema: zodSchema,
+  })
+
+  switch (format) {
+    case 'string':
+    case 'number': {
+      return object.result
+    }
+    case 'object':
+    case 'array': {
+      return JSON.stringify(object.result, null, 2)
+    }
+    default: {
+      throw new Error(`Can't format response for unknown format '${format}'`)
+    }
+  }
+}

package/src/utils/input.js

@@ -0,0 +1,56 @@
+import { readFile } from 'node:fs/promises'
+import { createInterface } from 'node:readline'
+
+/**
+ * Read content from a file.
+ *
+ * @param {string} filePath - Path to the file to read
+ * @returns {Promise<string>} The file content
+ */
+export const readFileContent = async (filePath) => {
+  try {
+    return await readFile(filePath, 'utf8')
+  } catch (error) {
+    throw new Error(`Failed to read file '${filePath}'`, { cause: error })
+  }
+}
+
+/**
+ * Read content from stdin.
+ *
+ * @returns {Promise<string>} The stdin content
+ */
+export const readStdin = () => {
+  const { promise, resolve, reject } = Promise.withResolvers()
+
+  let data = ''
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  })
+
+  rl.on('line', (line) => {
+    data += line + '\n'
+  })
+
+  rl.on('close', () => {
+    resolve(data.trim())
+  })
+
+  rl.on('error', (error) => {
+    reject(new Error(`Failed to read stdin`, { cause: error }))
+  })
+
+  return promise
+}
+
+/**
+ * Check if stdin has data available.
+ *
+ * @returns {boolean} True if stdin has data
+ */
+export const hasStdinData = () => {
+  return !process.stdin.isTTY
+}

package/src/utils/schema.js

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+
+/**
+ * Get the appropriate Zod schema for the requested format.
+ *
+ * @param {string} format - The output format
+ * @param {string} schemaString - The Zod schema string for object/array format
+ * @returns {z.ZodType} The Zod schema for the format
+ */
+export const getFormatSchema = (format, schemaString) => {
+  switch (format) {
+    case 'string': {
+      return z.object({
+        result: z.string(),
+      })
+    }
+    case 'number': {
+      return z.object({
+        result: z.number(),
+      })
+    }
+    case 'object': {
+      // Parse the schema string (e.g., "z.object({name:z.string()})")
+      // We need to evaluate it in the context of zod
+      // eslint-disable-next-line no-eval
+      const parsedSchema = eval(schemaString)
+      return z.object({
+        result: parsedSchema,
+      })
+    }
+    case 'array': {
+      // Parse the schema string (e.g., "z.string()" or "z.object({name:z.string()})")
+      // We need to evaluate it in the context of zod
+      // eslint-disable-next-line no-eval
+      const parsedSchema = eval(schemaString)
+      return z.object({
+        result: z.array(parsedSchema),
+      })
+    }
+    default: {
+      throw new Error(`Can't create schema for unknown format '${format}'`)
+    }
+  }
+}