@agentionai/agents 0.3.0-beta → 0.3.1

package/README.md

@@ -1,517 +1,217 @@
 # Agention
 
-> A TypeScript library for building AI-powered agents, tools, and complex workflows
+> AI Agents Without the Magic
 
 [![npm version](https://img.shields.io/npm/v/@agentionai/agents.svg)](https://www.npmjs.com/package/@agentionai/agents)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Agention provides a clean, modular architecture for working with LLMs from multiple providers. Build single-purpose agents or orchestrate complex multi-agent workflows with built-in tools, vector search, and document processing capabilities.
+A comprehensive TypeScript toolkit for building LLM-powered agents with RAG, and multi-agent workflows. No hidden state machines, no forced abstractions—just typed agents, composable graphs, and complete control in a complete toolkit.
 
-## Features
-
-- **🤖 Multi-Provider Support** - Works with Claude, OpenAI, Mistral, and Google Gemini out of the box
-- **🔧 Powerful Tool System** - Define tools with JSON Schema validation, agents use them automatically
-- **🔀 Graph Pipelines** - Chain agents together with sequential, parallel, map, voting, and router patterns
-- **💾 Vector Search** - Built-in LanceDB integration for semantic search and RAG applications
-- **📄 Document Processing** - Intelligent chunking with token-aware splitting and metadata tracking
-- **📊 Metrics & Observability** - Track tokens, timing, and pipeline execution
-- **🔒 Type-Safe** - Full TypeScript support with strict typing throughout
+**[Documentation](https://docs.agention.ai/)** • **[Examples](https://docs.agention.ai/guide/examples)** • **[GitHub](https://github.com/laurentzuijdwijk/agention-lib)**
 
-## Installation
+## Quick Start
 
 ```bash
 npm install @agentionai/agents
 ```
 
-Install the SDK for your chosen LLM provider:
+Install provider SDKs as needed:
 
 ```bash
-# For Claude
-npm install @anthropic-ai/sdk
-
-# For OpenAI
-npm install openai
-
-# For vector search (optional)
-npm install @lancedb/lancedb apache-arrow
+npm install @anthropic-ai/sdk  # For Claude
+npm install openai             # For OpenAI/GPT
+npm install @google/generative-ai  # For Gemini
+npm install @mistralai/mistralai   # For Mistral
 ```
 
-## Quick Start
-
-### Basic Agent
+### Simple Agent
 
 ```typescript
 import { ClaudeAgent } from '@agentionai/agents';
 
 const agent = new ClaudeAgent({
-  model: 'claude-sonnet-4-20250514',
-  systemPrompt: 'You are a helpful assistant.',
+  model: 'claude-sonnet-4-5',
+  name: 'Assistant',
+  description: 'You are a helpful assistant.',
 });
 
-const response = await agent.execute('What is the capital of France?');
+const response = await agent.execute('What can you help me with?');
 console.log(response);
 ```
 
+
+## Features
+
+- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral—same interface. Switch models with one line.
+- **Composable, Not Magical** - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
+- **Full Observability** - Per-call token counts, execution timing, pipeline structure visualization.
+- **TypeScript-Native** - Strict typing, interfaces, and generics from the ground up.
+- **RAG Ready** - LanceDB vector store, token-aware chunking, ingestion pipeline out of the box.
+
+
 ### Agent with Tools
 
 ```typescript
-import { ClaudeAgent, Tool } from '@agentionai/agents';
+import { GeminiAgent, Tool } from '@agentionai/agents';
 
-const calculator = new Tool({
-  name: 'calculate',
-  description: 'Perform mathematical calculations',
+const weatherTool = new Tool({
+  name: 'get_weather',
+  description: 'Get the current weather for a location',
   input_schema: {
     type: 'object',
     properties: {
-      expression: { type: 'string', description: 'Math expression to evaluate' },
+      location: { type: 'string', description: 'City name' },
     },
-    required: ['expression'],
+    required: ['location'],
   },
-  handler: async ({ expression }) => {
-    return String(eval(expression));
+  handler: async ({ location }) => {
+    // In production, call a weather API
+    return JSON.stringify({
+      location,
+      temperature: 22,
+      conditions: 'Sunny',
+    });
   },
 });
 
-const agent = new ClaudeAgent({
-  model: 'claude-sonnet-4-20250514',
-  systemPrompt: 'You are a helpful math assistant.',
-  tools: [calculator],
+const agent = new GeminiAgent({
+  model: 'gemini-flash-lite-latest',
+  name: 'Weather Agent',
+  description: 'You are a weather assistant.',
+  tools: [weatherTool],
 });
 
-const response = await agent.execute('What is 15% of 230?');
-// Agent automatically uses the calculator tool
+const response = await agent.execute("What's the weather in Paris?");
 ```
 
 ### Multi-Agent Pipeline
 
+Chain agents together with different providers and models:
+
 ```typescript
-import { Pipeline, ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
+import { ClaudeAgent, OpenAiAgent, Pipeline } from '@agentionai/agents';
 
-// Research agent with search capabilities
 const researcher = new OpenAiAgent({
-  name: 'researcher',
+  id: 'researcher',
+  name: 'Researcher',
+  description: 'Research the given topic and provide key facts.',
   model: 'gpt-4o',
-  systemPrompt: 'Research the topic thoroughly.',
-  tools: [webSearchTool],
+  tools: [searchTool],
 });
 
-// Writing agent
 const writer = new ClaudeAgent({
-  name: 'writer',
-  model: 'claude-sonnet-4-20250514',
-  systemPrompt: 'Write a compelling blog post from the research.',
+  id: 'writer',
+  name: 'Writer',
+  description: 'Write a blog post based on the research provided.',
+  model: 'claude-sonnet-4-5',
 });
 
-// Chain them together
 const pipeline = new Pipeline([researcher, writer]);
-const result = await pipeline.execute('AI in Healthcare');
-// researcher output → writer input → final blog post
-```
-
-### RAG with Vector Search
-
-```typescript
-import { ClaudeAgent, LanceDBVectorStore, OpenAIEmbeddings } from '@agentionai/agents';
-
-// Setup vector store
-const embeddings = new OpenAIEmbeddings({ model: 'text-embedding-3-small' });
-const store = await LanceDBVectorStore.create({
-  name: 'docs',
-  uri: './data/vectors',
-  tableName: 'knowledge',
-  embeddings,
-});
-
-// Add documents
-await store.addDocuments([
-  { id: '1', content: 'Company policy on refunds...' },
-  { id: '2', content: 'Technical documentation...' },
-]);
-
-// Create search tool
-const searchTool = store.toRetrievalTool(
-  'Search company knowledge base',
-  { defaultLimit: 5 }
-);
-
-// Agent can search and answer
-const agent = new ClaudeAgent({
-  model: 'claude-sonnet-4-20250514',
-  systemPrompt: 'Answer questions using the knowledge base.',
-  tools: [searchTool],
-});
-
-const answer = await agent.execute('What is our refund policy?');
-```
-
-## Core Concepts
-
-### Agents
-
-Agents wrap LLM providers with a consistent interface. All agents support:
-
-- Conversation history management
-- Tool use
-- Token tracking
-- Pipeline integration
-
-```typescript
-import { ClaudeAgent, OpenAiAgent, MistralAgent, GeminiAgent } from '@agentionai/agents';
-
-// Same interface, different providers
-const claude = new ClaudeAgent({ model: 'claude-sonnet-4-20250514' });
-const openai = new OpenAiAgent({ model: 'gpt-4o' });
-const mistral = new MistralAgent({ model: 'mistral-large-latest' });
-const gemini = new GeminiAgent({ model: 'gemini-2.0-flash' });
+const result = await pipeline.execute('Renewable energy trends in 2024');
 ```
 
-### Tools
-
-Tools give agents abilities beyond text generation. Define them with JSON Schema:
-
-```typescript
-const weatherTool = new Tool({
-  name: 'get_weather',
-  description: 'Get current weather for a city',
-  input_schema: {
-    type: 'object',
-    properties: {
-      city: { type: 'string' },
-      units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
-    },
-    required: ['city'],
-  },
-  handler: async ({ city, units }) => {
-    const weather = await fetchWeather(city, units);
-    return JSON.stringify(weather);
-  },
-});
-```
-
-**Advanced: Agents as Tools**
+### Agent Delegation
 
 Use agents as tools for hierarchical workflows:
 
 ```typescript
-// Specialized sub-agent
+import { ClaudeAgent, OpenAiAgent, Tool } from '@agentionai/agents';
+
+// Research assistant (cheaper model for data gathering)
 const researchAssistant = new OpenAiAgent({
-  name: 'research-assistant',
-  description: 'Expert at finding research papers',
-  tools: [pubmedSearchTool],
+  id: 'research-assistant',
+  name: 'Research Assistant',
+  description: 'Search and summarize information on topics.',
   model: 'gpt-4o-mini',
+  tools: [searchTool],
 });
 
-// Main agent delegates to sub-agent
-const mainAgent = new ClaudeAgent({
-  name: 'coordinator',
-  agents: [researchAssistant],  // Sub-agents available as tools
-  model: 'claude-sonnet-4-20250514',
-});
-```
-
-### Graph Pipelines
-
-Build complex workflows by combining agents and executors:
-
-#### Sequential Processing
-
-```typescript
-import { SequentialExecutor } from '@agentionai/agents';
-
-const chain = new SequentialExecutor({
-  name: 'content-pipeline',
-  agents: [researcher, writer, editor],
-});
-// researcher → writer → editor
-```
-
-#### Parallel Execution
-
-```typescript
-import { ParallelExecutor } from '@agentionai/agents';
-
-const parallel = new ParallelExecutor({
-  name: 'multi-perspective',
-  agents: [optimist, pessimist, realist],
-});
-// All run simultaneously on same input
-```
-
-#### Map Operations
-
-```typescript
-import { MapExecutor } from '@agentionai/agents';
-
-const mapper = new MapExecutor({
-  name: 'batch-process',
-  processor: summarizer,
-});
-
-await mapper.execute(['doc1', 'doc2', 'doc3']);
-// Applies summarizer to each document
-```
-
-#### Voting Systems
-
-```typescript
-import { VotingSystem } from '@agentionai/agents';
-
-const voting = new VotingSystem({
-  name: 'code-review',
-  candidates: [juniorDev, seniorDev, architect],
-  judge: techLead,
+// Lead researcher delegates to assistant, synthesizes findings
+const researcher = new ClaudeAgent({
+  id: 'researcher',
+  name: 'Lead Researcher',
+  description: 'Research topics thoroughly using your assistant.',
+  model: 'claude-sonnet-4-5',
+  agents: [researchAssistant],  // Assistant available as a tool
 });
-// Multiple solutions proposed, judge picks best
-```
-
-#### Router Patterns
 
-```typescript
-import { RouterExecutor } from '@agentionai/agents';
-
-const router = new RouterExecutor({
-  name: 'support-router',
-  routes: [
-    { name: 'billing', agent: billingAgent, description: 'Billing questions' },
-    { name: 'technical', agent: techAgent, description: 'Technical issues' },
-  ],
-  routerAgent: classifierAgent,
-});
-// Routes input to appropriate agent
+const result = await researcher.execute('Latest developments in quantum computing');
 ```
 
-### Document Processing
-
-#### Chunking Strategies
-
-Split documents intelligently for RAG applications:
-
-```typescript
-import { RecursiveChunker, TokenChunker, TextChunker } from '@agentionai/agents';
-
-// Semantic chunking (best for structured docs)
-const recursiveChunker = new RecursiveChunker({
-  chunkSize: 1000,
-  chunkOverlap: 100,
-  separators: ['\n\n', '\n', '. ', ' '],
-});
-
-// Token-aware chunking (best for LLM context limits)
-const tokenChunker = new TokenChunker({
-  chunkSize: 500,  // tokens, not characters
-  chunkOverlap: 50,
-});
-
-// Simple character-based chunking
-const textChunker = new TextChunker({
-  chunkSize: 1000,
-  chunkOverlap: 200,
-});
-
-const chunks = await recursiveChunker.chunk(documentText, {
-  sourceId: 'doc-123',
-  metadata: { author: 'Alice' },
-});
-```
+## Core Concepts
 
-#### Ingestion Pipeline
+### Agents
+Unified interface across Claude, OpenAI, Gemini, and Mistral. Tools, history, and token tracking built-in.
 
-Orchestrate chunking, embedding, and storage:
+[Learn more →](https://docs.agention.ai/guide/agents)
 
-```typescript
-import { IngestionPipeline, RecursiveChunker } from '@agentionai/agents';
-
-const chunker = new RecursiveChunker({ chunkSize: 1000 });
-const embeddings = new OpenAIEmbeddings({ model: 'text-embedding-3-small' });
-const store = await LanceDBVectorStore.create({
-  name: 'docs',
-  uri: './data',
-  tableName: 'chunks',
-  embeddings,
-});
+### Tools
+JSON Schema + handler pattern. Unique capability: wrap any agent as a tool for delegation hierarchies.
 
-const pipeline = new IngestionPipeline(chunker, embeddings, store);
+[Learn more →](https://docs.agention.ai/guide/tools)
 
-const result = await pipeline.ingest(documentText, {
-  sourceId: 'doc-001',
-  batchSize: 50,
-  onProgress: ({ phase, processed, total }) => {
-    console.log(`${phase}: ${processed}/${total}`);
-  },
-});
-```
+### History
+Provider-agnostic, persistent (Redis, file, custom), shareable across agents of different providers.
 
-### Metrics & Observability
+[Learn more →](https://docs.agention.ai/guide/history)
 
-Track performance across your pipelines:
+### Graph Pipelines
+Compose sequential, parallel, voting, routing, and nested graphs. Mix models and providers freely.
 
-```typescript
-import { MetricsCollector } from '@agentionai/agents';
+[Learn more →](https://docs.agention.ai/guide/graph-pipelines)
 
-const metrics = new MetricsCollector();
-const result = await pipeline.execute('Input', { metrics });
+### RAG & Vector Stores
+LanceDB vector store, token-aware chunking, ingestion pipeline, and retrieval tools out of the box.
 
-const stats = metrics.getMetrics();
-console.log({
-  totalDuration: stats.totalDuration,
-  totalTokens: stats.totalInputTokens + stats.totalOutputTokens,
-  nodeCount: stats.nodes.length,
-});
+[Learn more →](https://docs.agention.ai/guide/vector-stores)
 
-// Per-node metrics
-stats.nodes.forEach(node => {
-  console.log(`${node.name}: ${node.duration}ms, ${node.tokens?.total} tokens`);
-});
-```
+### Observability
+Per-call and per-node token counts, duration metrics, full execution visibility.
 
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Agention                              │
-│                                                              │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
-│  │  Claude  │  │  OpenAI  │  │ Mistral  │  │  Gemini  │   │
-│  │  Agent   │  │  Agent   │  │  Agent   │  │  Agent   │   │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
-│       │             │               │             │          │
-│       └─────────────┴───────────────┴─────────────┘          │
-│                          │                                   │
-│                    ┌─────▼─────┐                            │
-│                    │ BaseAgent │                            │
-│                    │ Interface │                            │
-│                    └─────┬─────┘                            │
-│                          │                                   │
-│       ┌──────────────────┼──────────────────┐              │
-│       │                  │                  │              │
-│  ┌────▼────┐       ┌─────▼─────┐     ┌─────▼─────┐       │
-│  │  Tools  │       │ Pipelines │     │  History  │       │
-│  └─────────┘       └───────────┘     └───────────┘       │
-│       │                  │                                   │
-│  ┌────▼────────────┐     │                                   │
-│  │ Vector Stores   │     │                                   │
-│  │  - LanceDB      │     │                                   │
-│  │  - Embeddings   │     │                                   │
-│  └─────────────────┘     │                                   │
-│                          │                                   │
-│       ┌──────────────────┼──────────────────┐              │
-│       │                  │                  │              │
-│  ┌────▼────┐       ┌─────▼─────┐     ┌─────▼─────┐       │
-│  │Sequential│      │ Parallel  │     │   Router  │       │
-│  │Executor  │      │ Executor  │     │  Executor │       │
-│  └──────────┘      └───────────┘     └───────────┘       │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
+[Learn more →](https://docs.agention.ai/guide/graph-pipelines#metrics--observability)
 
 ## Documentation
 
-- **[Getting Started](docs/guide/getting-started.md)** - Installation and first steps
-- **[Agents](docs/guide/agents.md)** - Agent configuration and providers
-- **[Tools](docs/guide/tools.md)** - Creating and using tools
-- **[Graph Pipelines](docs/guide/graph-pipelines.md)** - Building multi-agent workflows
-- **[Vector Stores](docs/guide/vector-stores.md)** - Semantic search and RAG
-- **[Chunking & Ingestion](docs/guide/chunking-and-ingestion.md)** - Document processing
-- **[Examples](docs/guide/examples.md)** - Complete example applications
-- **[API Reference](docs/api)** - Full API documentation
+- **[Getting Started](https://docs.agention.ai/guide/getting-started)** - Installation and first agent
+- **[Quick Start](https://docs.agention.ai/guide/quickstart)** - Build a weather assistant in 5 minutes
+- **[Agents](https://docs.agention.ai/guide/agents)** - Agent configuration and providers
+- **[Tools](https://docs.agention.ai/guide/tools)** - Adding capabilities and agent delegation
+- **[Graph Pipelines](https://docs.agention.ai/guide/graph-pipelines)** - Multi-agent workflows
+- **[Vector Stores](https://docs.agention.ai/guide/vector-stores)** - RAG and semantic search
+- **[Examples](https://docs.agention.ai/guide/examples)** - Real-world implementations
+- **[API Reference](https://docs.agention.ai/api)** - Full API documentation
+
+## Why Agention?
+
+|  | Raw SDKs | Heavy Frameworks | Agention |
+|---|---|---|---|
+| **Control** | Full | Limited | Full |
+| **Boilerplate** | High | Low | Low |
+| **Transparency** | Full | Limited | Full |
+| **Multi-provider** | Manual | Varies | Built-in |
+| **TypeScript** | Varies | Often partial | Native |
+
+- **Ship faster** — Stop rebuilding agent infrastructure for every project
+- **Stay flexible** — Swap providers, mix models, customize everything
+- **Keep control** — See exactly what's happening at every step
+- **Scale confidently** — Built-in metrics, token tracking, and observability
 
 ## Examples
 
-See the [examples](examples) directory for complete working examples:
-
-- **Basic Agents** - Simple agent usage with different providers
-- **Tool Usage** - Agents with custom tools
-- **Multi-Agent Pipelines** - Sequential, parallel, and voting patterns
-- **RAG Applications** - Vector search and document retrieval
-- **Document Ingestion** - Chunking and embedding pipelines
-- **Graph-based RAG** - Advanced knowledge graph integration
-
-## Development
-
-### Commands
-
-```bash
-# Build
-npm run build
-
-# Test
-npm test
-npm run test:watch
-
-# Linting
-npm run lint
-npm run lint:fix
-
-# Documentation
-npm run docs:dev      # Start docs dev server
-npm run docs:build    # Build documentation
-npm run docs:api      # Generate API docs
-
-# Examples
-npm run example       # Run example code
-```
-
-### Project Structure
-
-```
-agention-lib/
-├── lib/
-│   ├── agents/           # Agent implementations
-│   │   ├── anthropic/    # Claude agent
-│   │   ├── openai/       # OpenAI agent
-│   │   ├── mistral/      # Mistral agent
-│   │   ├── google/       # Gemini agent
-│   │   └── BaseAgent.ts  # Abstract base class
-│   ├── tools/            # Tool system
-│   ├── history/          # Conversation management
-│   ├── graph/            # Pipeline executors
-│   │   ├── executors/    # Sequential, Parallel, Map, Voting, Router
-│   │   ├── MetricsCollector.ts
-│   │   └── Pipeline.ts
-│   ├── chunking/         # Document chunking
-│   │   ├── TextChunker.ts
-│   │   ├── RecursiveChunker.ts
-│   │   └── TokenChunker.ts
-│   ├── ingestion/        # Ingestion pipeline
-│   └── vectorstore/      # Vector store implementations
-│       ├── LanceDBVectorStore.ts
-│       └── embeddings/
-├── examples/             # Example applications
-├── docs/                 # Documentation
-└── dist/                 # Build output
-```
+Check out the [examples](https://github.com/laurentzuijdwijk/agention-lib/tree/master/examples) directory for complete working examples:
 
-## Environment Variables
-
-Set API keys as environment variables:
-
-```bash
-# LLM Providers
-export ANTHROPIC_API_KEY=your-key-here
-export OPENAI_API_KEY=your-key-here
-export MISTRAL_API_KEY=your-key-here
-export GOOGLE_API_KEY=your-key-here
-```
+- Basic agents with different providers
+- Custom tools and agent delegation
+- Sequential, parallel, and voting pipelines
+- RAG applications with vector search
+- Document ingestion and chunking
 
 ## Contributing
 
-Contributions are welcome! Please see our development guidelines in [CLAUDE.md](CLAUDE.md).
-
-## License
-
-MIT
-
-## Roadmap
-
-- [ ] Streaming response support
-- [ ] Additional vector store integrations (Pinecone, Weaviate)
-- [ ] Conditional and loop executors
-- [ ] Graph visualization tools
-- [ ] Enhanced retry mechanisms
-- [ ] Middleware system for request/response processing
+Contributions are welcome! Please open an issue or submit a pull request.
 
-## Support
+## Links
 
-- **Issues**: [GitHub Issues](https://github.com/laurentzuijdwijk/agention-lib/issues)
-- **Documentation**: [docs](docs/guide/getting-started.md)
-- **Examples**: [examples](examples)
+- **[Documentation](https://docs.agention.ai/)**
+- **[GitHub](https://github.com/laurentzuijdwijk/agention-lib)**
+- **[npm](https://www.npmjs.com/package/@agentionai/agents)**
+- **[Issues](https://github.com/laurentzuijdwijk/agention-lib/issues)**

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "0.3.0-beta",
+  "version": "0.3.1",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "README.md",
-    "LICENSE"
+    "README.md"
   ],
   "repository": {
     "type": "git",
@@ -32,7 +31,7 @@
     "docs:site": "vitepress build docs",
     "docs:dev": "vitepress dev docs",
     "docs:preview": "vitepress preview docs",
-    "publish:npm": "npm publish --registry=https://registry.npmjs.org",
+    "publish:npm": "npm publish --registry=https://registry.npmjs.org --access public",
     "publish:github": "npm publish --registry=https://npm.pkg.github.com",
     "publish:all": "npm run publish:npm && npm run publish:github"
   },

package/readme.md

@@ -1 +0,0 @@
-Readme for atomic agents