Cogitator-AI

<p align="center">
  <img src="logo.png" alt="Cogitator" width="200">
</p>

<div align="center">

# Cogitator

### AI agents that actually do things.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Node](https://img.shields.io/badge/Node-20+-green.svg)](https://nodejs.org/)
[![npm](https://img.shields.io/npm/v/@cogitator-ai/core.svg)](https://www.npmjs.com/package/@cogitator-ai/core)

[Quick Start](#-quick-start) · [Examples](./examples) · [Docs](https://cogitator.app/docs) · [Discord](https://discord.gg/SkmRsYvA)

</div>

---

## What is Cogitator?

You know how Gemini and Gemini are great at _talking_? Cogitator makes AI that can _do things_.

An **agent** is an AI that has **tools** - it can search the web, read files, call APIs, write code, run queries. You give it a goal, it figures out which tools to use and in what order.

Cogitator is a TypeScript framework for building these agents. One agent or a hundred, local model or cloud API, simple script or production service - same code, same patterns.

```typescript
import { Cogitator, Agent, tool } from '@cogitator-ai/core';
import { z } from 'zod';

const weather = tool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => `${city}: 22°C, sunny`,
});

const agent = new Agent({
  name: 'assistant',
  model: 'google/gemini-2.5-flash', // free tier, no credit card
  instructions: 'You help people with questions. Use tools when needed.',
  tools: [weather],
});

const cog = new Cogitator();
const result = await cog.run(agent, { input: 'What is the weather in Tokyo?' });
console.log(result.output);
```

That's it. The agent reads your question, decides to call `get_weather`, gets the result, and writes a human-friendly response.

---

## Quick Start

**Opt