aivok

A unified JavaScript/TypeScript library for calling AI language models — with zero boilerplate, automatic provider fallback, agentic tool loops, and custom AI personas.

---

Why aivok?

• One import, every provider — Gemini, Groq, Anthropic, Mistral, Cohere, OpenAI, Ollama, OpenRouter, and any OpenAI-compatible API
• Zero boilerplate — retries, rate limit backoff, message history, tool formatting handled automatically
• Provider-agnostic — swap models by changing one config line
• TypeScript native — full type safety, works seamlessly in JS and TS projects
• Zero runtime dependencies — lightweight, auditable, no bloat

---

Quick Start

npm install aivok

import { createAivok } from 'aivok'

### One-line setup (auto-detects API keys from `.env`)

```js
import 'dotenv/config'
import { createAivok } from 'aivok'

const ai = createAivok()
const answer = await ai.ask('Explain async/await in JavaScript')
console.log(answer)

Explicit configuration

import { createAivok } from 'aivok'

const ai = createAivok({
  provider: 'gemini',
  model:    'gemini-2.0-flash',
  apiKey:   process.env.GEMINI_API_KEY,
})

---

Supported Providers

Provider	Description
Gemini	Google Gemini — large context window
Groq	Groq — fast inference
Anthropic	Anthropic Claude — careful reasoning
Mistral	Mistral AI — multilingual
Cohere	Cohere — enterprise, RAG
OpenAI	OpenAI GPT models
OpenAI-compatible	Ollama, OpenRouter, DeepSeek, xAI

See docs/providers.md for setup guides and API key instructions.

---

Features

Single question

const reply = await ai.ask('What is the capital of France?')

Multi-turn chat

const session = ai.chat()
await session.send('Explain closures in JavaScript')
await session.send('Give me a real-world example')

Streaming

await ai.stream('Write a story', (chunk) => process.stdout.write(chunk))

Structured JSON

const data = await ai.json('List 5 JS frameworks with name and year')
// Returns parsed JavaScript object

Custom persona

const ai = createAivok({
  provider: 'gemini',
  persona: {
    name:  'Nova',
    role:  'a helpful portfolio assistant',
    tone:  'friendly and concise',
    rules: ['keep answers short', 'only discuss my projects'],
  },
})

Provider fallback

const ai = createAivok({
  providers: [
    { name: 'gemini', model: 'gemini-2.0-flash', apiKey: process.env.GEMINI_API_KEY, primary: true },
    { name: 'groq',   model: 'llama-3.3-70b-versatile', apiKey: process.env.GROQ_API_KEY },
  ],
})
// Tries Gemini first, automatically falls back to Groq on rate limit

Agentic tool loop

const result = await ai.agent({
  goal: 'Read package.json, bump the patch version, save it back',
  tools: {
    readFile:  { description: 'Read a file', params: { path: 'string' }, run: async ({ path }) => fs.readFileSync(path, 'utf8') },
    writeFile: { description: 'Write a file', params: { path: 'string', content: 'string' }, run: async ({ path, content }) => { fs.writeFileSync(path, content); return 'done' } },
  },
  maxSteps: 5,
})

console.log(result.answer)     // final response
console.log(result.steps)      // audit trail

Built-in persona presets

import { createAivok, personas } from 'aivok'

const ai = createAivok({ ..., persona: personas.coder })
// personas.support | personas.tutor | personas.writer | personas.coder

---

Documentation

Guide	Description
API Reference	Every function, parameter, and return type
Providers	Setup guides and API key instructions
Agents	Tool loop, tool definition format, examples
Personas	Custom AI identities, presets
Examples	Annotated copy-paste examples

---

Error Handling

All methods throw errors with a code property:

try {
  const reply = await ai.ask('Hello')
} catch (err) {
  if (err.code === 'RATE_LIMIT')    console.log('All providers rate limited')
  if (err.code === 'AUTH_ERROR')    console.log('Invalid API key')
  if (err.code === 'MAX_STEPS')     console.log('Agent exceeded maxSteps')
  if (err.code === 'PARSE_ERROR')   console.log('Invalid JSON response')
}

---

Author

Built by @tyecode

---

License

MIT