npm package: @rodgerai/core
Description: Headless AI agent SDK - Build agents in minutes, not days
Author: William Kasel
Latest version: 2.0.0

# @rodger/core

Build production-ready AI agents in minutes, not days.

## Features

- Simple API - Create agents with <20 lines of code
- Multi-Provider - OpenAI, Anthropic, and more
- Tool System - Type-safe tools with automatic validation
- Knowledge & RAG - Integrate Zep, Ragie, LlamaParse, Firecrawl
- Guardrails - Input/output validation for safe agents
- Lifecycle Hooks - Observe and control agent execution
- Streaming Support - Real-time response streaming
- TypeScript-First - Fully typed with excellent IDE support

## Installation

```bash
npm install @rodger/core
# or
pnpm add @rodger/core
```

## Quick Start

```typescript
import { createAgent } from '@rodger/core';

const agent = createAgent({
  name: 'Support Agent',
  llm: { provider: 'openai', model: 'gpt-4o' }
});

const response = await agent.chat('Hello!');
console.log(response.text);
```

## Core Concepts

### Agent Configuration

Create agents with flexible configuration:

```typescript
import { createAgent } from '@rodger/core';
import { z } from 'zod';

const agent = createAgent({
  name: 'My Agent',

  // LLM configuration
  llm: {
    provider: 'openai',
    model: 'gpt-4o',
    temperature: 0.7
  },

  // System instructions
  systemPrompt: 'You are a helpful assistant.',

  // Custom tools (optional)
  tools: {
    calculator: {
      name: 'calculator',
      description: 'Performs arithmetic',
      parameters: z.object({
        a: z.number(),
        b: z.number()
      }),
      execute: async ({ a, b }) => a + b
    }
  },

  // Guardrails (optional)
  guardrails: {
    input: [(input) => input.length < 1000 || 'Input too long'],
    output: [(output) => !output.includes('unsafe') || 'Unsafe content']
  }
});
```

### Streaming Responses

Stream responses in real-time:

```typescript
// Stream text chunks
for await (const chunk of agent.stream('Tell me a story')) {
  process.stdout.write(chunk);
}

// Or with full control
const stream = agent.streamWithEvents('Tell me a story');
for await (const event of stream) {
  if (event.type === 'text-delta') {
    console.log(event.textDelta);
  } else if (event.type === 'tool-call') {
    console.log('Tool called:', event.toolName);
  }
}
```

### Tool Integration

Define custom tools with type safety:

```typescript
import { createAgent } from '@rodger/core';
import { z } from 'zod';

const weatherTool = {
  name: 'getWeather',
  description: 'Get weather for a location',
  parameters: z.object({
    location: z.string(),
    unit: z.enum(['celsius', 'fahrenheit']).optional()
  }),
  execute: async ({ location, unit = 'celsius' }) => {
    // Fetch weather data
    const data = await fetch(`/api/weather?location=${location}`);
    return data.json();
  }
};

const agent = createAgent({
  name: 'Weather Agent',
  llm: { provider: 'openai', model: 'gpt-4o' },
  tools: { getWeather: weatherTool }
});

// Agent automatically calls tool when needed
const response = await agent.chat('What is the weather in Paris?');
```

### Constants and Defaults

All default values and limits can be overridden via configuration:

```typescript
import { createAgent, KNOWLEDGE_DEFAULTS } from '@rodger/core';

// Use exported constants
console.log(KNOWLEDGE_DEFAULTS.TOP_K); // 3

// Override defaults
const agent = createAgent({
  defaults: {
    knowledge: { topK: 5 }
  }
});
```

See [CONSTANTS.md](./CONSTANTS.md) for full documentation.

### Lifecycle Hooks

Monitor and control agent execution:

```typescript
import { createAgent, AgentLifecycleHooks } from '@rodger/core';

const hooks: AgentLifecycleHooks = {
  onBeforeRun: async (input, context) => {
    console.log('Starting run:', input);
  },

  onAfterRun: async (output, context) => {
    console.log('Completed run:', output);
  },

  onBeforeToolCall: async (toolName, args, context) => {
    console.log('Calling tool:', toolName);
    return true; // Return false to block execution
  },

  onAfterToolCall: async (toolName, result, context) => {
    console.log('Tool completed:', toolName);
  },

  onToolApproval: async (toolName, args, context) => {
    // Custom approval logic
    return await showConfirmationDialog(toolName, args);
  },

  onStreamEvent: async (event, context) => {
    // Handle streaming events
    if (event.type === 'chunk') {
      console.log(event.delta);
    }
  },

  onError: async (error, context) => {
    console.error('Agent error:', error);
  }
};

const agent = createAgent({
  name: 'Monitored Agent',
  llm: { provider: 'openai', model: 'gpt-4o' },
  hooks
});
```

See [docs/LIFECYCLE-HOOKS.md](./docs/LIFECYCLE-HOOKS.md) for complete documentation.

### Knowledge Integration

Enhance agents with memory and RAG:

```typescript
import { createAgent } from '@rodger/core';
import { ZepKnowledge } from '@rodger/core/knowledge';

// Conversation memory with Zep
const agent = createAgent({
  name: 'Memory Agent',
  llm: { provider: 'openai', model: 'gpt-4o' },
  knowledge: new ZepKnowledge({
    apiKey: process.env.ZEP_API_KEY,
    collectionName: 'conversations'
  })
});

// Agent remembers previous messages
await agent.chat('My name is Alice', { sessionId: 'user-123' });
await agent.chat('What is my name?', { sessionId: 'user-123' });
// Response: "Your name is Alice"
```

### Guardrails

Add validation for safe agent behavior:

```typescript
const agent = createAgent({
  name: 'Safe Agent',
  llm: { provider: 'openai', model: 'gpt-4o' },

  guardrails: {
    // Input validation
    input: [
      (input) => input.length < 5000 || 'Input too long',
      (input) => !input.includes('hack') || 'Unsafe content detected'
    ],

    // Output validation
    output: [
      (output) => output.length < 10000 || 'Response too long',
      (output) => !containsPII(output) || 'PII detected in output'
    ]
  }
});
```

## Supported Providers

### LLM Providers
- **OpenAI** - GPT-4, GPT-4o, GPT-3.5
- **Anthropic** - Claude 3.5 Sonnet, Claude 3 Opus/Haiku

### Knowledge Providers
- **Zep** - Conversation memory and context
- **Ragie** - Document RAG and semantic search
- **Firecrawl** - Web scraping and crawling
- **LlamaParse** - Document parsing and extraction

## API Reference

### `createAgent(config)`

Creates a new agent instance.

**Parameters:**
- `name` (string) - Agent identifier
- `llm` (LLMConfig) - LLM provider configuration
- `systemPrompt` (string, optional) - System instructions
- `tools` (Record<string, Tool>, optional) - Custom tools
- `knowledge` (Knowledge, optional) - Knowledge provider
- `guardrails` (Guardrails, optional) - Input/output validation
- `hooks` (AgentLifecycleHooks, optional) - Lifecycle hooks

**Returns:** `Agent` instance

### `agent.chat(message, options?)`

Send a message and get a response.

**Parameters:**
- `message` (string) - User message
- `options.sessionId` (string, optional) - Session identifier for memory
- `options.userId` (string, optional) - User identifier
- `options.metadata` (Record<string, unknown>, optional) - Custom metadata

**Returns:** `Promise<AgentResponse>`

### `agent.stream(message, options?)`

Stream response chunks.

**Parameters:** Same as `chat()`

**Returns:** `AsyncIterable<string>` - Text chunks

### `agent.streamWithEvents(message, options?)`

Stream with full event control.

**Returns:** `AsyncIterable<StreamEvent>` - Stream events

## TypeScript Support

Full TypeScript support with type inference:

```typescript
import type {
  Agent,
  AgentConfig,
  AgentResponse,
  Tool,
  AgentLifecycleHooks,
  HookContext,
  StreamEvent
} from '@rodger/core';
```

## Related Packages

- **[@rodger/ui](../ui)** - React components for agent UIs
- **[@rodger/tools](../tools)** - Pre-built tool library
- **[@rodger/widgets](../widgets)** - UI widgets for tools
- **[@rodger/cli](../cli)** - CLI for testing agents

## Examples

Check out the [examples directory](../../examples) for complete examples:

- [Basic Chat](../../examples/basic-chat) - Simple chat agent
- [Tool Agent](../../examples/tool-agent) - Agent with custom tools
- [Knowledge Agent](../../examples/knowledge-agent) - Agent with RAG
- [Loan Assistant](../../examples/loan-assistant) - Production example

## Documentation

Full documentation: [docs.rodger.ai](https://docs.rodger.ai)

## License

MIT