@falai/agent 0.1.0

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -0,0 +1,256 @@
+# Constructor Configuration Guide
+
+## Overview
+
+The `@falai/agent` framework supports **two complementary patterns** for configuration:
+
+1. **Declarative** - Pass arrays/objects in constructors (great for static configs)
+2. **Fluent/Programmatic** - Chain methods to build dynamically (great for runtime logic)
+
+You can **mix both patterns** - initialize with constructor options, then add more dynamically!
+
+---
+
+## 📦 Agent Constructor Options
+
+```typescript
+interface AgentOptions<TContext = unknown> {
+  // Required
+  name: string;
+  ai: AiProvider;
+  
+  // Optional metadata
+  description?: string;
+  goal?: string;
+  context?: TContext;
+  
+  // Configuration
+  maxEngineIterations?: number;
+  compositionMode?: CompositionMode;
+  
+  // Declarative initialization (NEW!)
+  terms?: Term[];
+  guidelines?: Guideline[];
+  capabilities?: Capability[];
+  routes?: RouteOptions[];
+  observations?: ObservationOptions[];
+}
+```
+
+### Example: Full Declarative Agent
+
+```typescript
+const agent = new Agent({
+  name: "SupportBot",
+  description: "Helpful customer support",
+  goal: "Resolve issues efficiently",
+  ai: new GeminiProvider({ apiKey: "..." }),
+  context: { userId: "123" },
+  
+  terms: [
+    { name: "SLA", description: "Service Level Agreement", synonyms: ["response time"] }
+  ],
+  
+  guidelines: [
+    {
+      condition: "User is frustrated",
+      action: "Show empathy and offer escalation",
+      tags: ["support"],
+      enabled: true
+    }
+  ],
+  
+  capabilities: [
+    { title: "Ticket Management", description: "Create and track tickets" }
+  ],
+  
+  routes: [
+    {
+      title: "Create Ticket",
+      description: "Help user create a support ticket",
+      conditions: ["User wants to report an issue"],
+      guidelines: [
+        { condition: "Issue is urgent", action: "Prioritize immediately" }
+      ]
+    }
+  ],
+  
+  observations: [
+    {
+      description: "User mentions problem but unclear what kind",
+      routeRefs: ["Create Ticket", "Check Ticket Status"] // By title!
+    }
+  ]
+});
+```
+
+---
+
+## 🛤️ Route Constructor Options
+
+```typescript
+interface RouteOptions {
+  // Required
+  title: string;
+  
+  // Optional
+  description?: string;
+  conditions?: string[];
+  guidelines?: Guideline[]; // NEW!
+}
+```
+
+### Example: Route with Nested Guidelines
+
+```typescript
+const agent = new Agent({
+  name: "Bot",
+  ai: provider,
+  routes: [
+    {
+      title: "Onboarding",
+      description: "Guide new users",
+      conditions: ["User is new"],
+      guidelines: [
+        {
+          condition: "User skips a step",
+          action: "Gently remind them it's important",
+          tags: ["onboarding"]
+        },
+        {
+          condition: "User seems confused",
+          action: "Offer a quick tutorial video",
+          tags: ["help"]
+        }
+      ]
+    }
+  ]
+});
+```
+
+---
+
+## 🔍 Observation Options
+
+```typescript
+interface ObservationOptions {
+  description: string;
+  routeRefs?: string[]; // NEW! Reference routes by ID or title
+}
+```
+
+### Example: Observations with Route References
+
+```typescript
+const agent = new Agent({
+  name: "HealthBot",
+  ai: provider,
+  routes: [
+    { title: "Schedule Appointment", conditions: [...] },
+    { title: "Cancel Appointment", conditions: [...] },
+    { title: "Reschedule Appointment", conditions: [...] }
+  ],
+  observations: [
+    {
+      description: "User mentions appointment but intent unclear",
+      routeRefs: ["Schedule Appointment", "Reschedule Appointment"]
+    },
+    {
+      description: "User wants to change something about their visit",
+      routeRefs: ["Cancel Appointment", "Reschedule Appointment"]
+    }
+  ]
+});
+```
+
+---
+
+## 🔄 Fluent API (Still Available!)
+
+All constructor options also have fluent methods that **return `this`** for chaining:
+
+```typescript
+agent
+  .createTerm({ name: "API", description: "..." })
+  .createGuideline({ condition: "...", action: "..." })
+  .createCapability({ title: "...", description: "..." });
+
+const route = agent.createRoute({ title: "..." });
+route.createGuideline({ condition: "...", action: "..." });
+
+const obs = agent.createObservation("User intent unclear");
+obs.disambiguate([route1, route2]);
+```
+
+---
+
+## 🎨 Best Practices
+
+### Use Declarative When:
+- ✅ Configuration is **static** and known upfront
+- ✅ Loading config from **JSON/YAML files**
+- ✅ Building **reusable agent templates**
+- ✅ You want **clean, readable initialization**
+
+### Use Fluent When:
+- ✅ Logic is **dynamic** or **conditional**
+- ✅ Building routes with **complex state machines**
+- ✅ Adding features **based on runtime conditions**
+- ✅ You prefer **step-by-step construction**
+
+### Mix Both!
+```typescript
+// Start with static config
+const agent = new Agent({
+  name: "Bot",
+  ai: provider,
+  terms: loadTermsFromFile(),
+  guidelines: loadGuidelinesFromDB(),
+});
+
+// Add dynamic features
+if (user.isPremium) {
+  agent.createGuideline({
+    condition: "User asks for priority support",
+    action: "Escalate immediately to premium team"
+  });
+}
+```
+
+---
+
+## 📊 Complete Comparison
+
+| Feature | Declarative (Constructor) | Fluent (Methods) |
+|---------|--------------------------|------------------|
+| **Terms** | `terms: Term[]` | `agent.createTerm(...)` |
+| **Guidelines** | `guidelines: Guideline[]` | `agent.createGuideline(...)` |
+| **Capabilities** | `capabilities: Capability[]` | `agent.createCapability(...)` |
+| **Routes** | `routes: RouteOptions[]` | `agent.createRoute(...)` |
+| **Route Guidelines** | `route.guidelines: Guideline[]` | `route.createGuideline(...)` |
+| **Observations** | `observations: ObservationOptions[]` | `agent.createObservation(...)` |
+| **Disambiguation** | `routeRefs: string[]` | `obs.disambiguate([...])` |
+
+---
+
+## 🚀 Quick Reference
+
+```typescript
+// Everything in one place
+const agent = new Agent<MyContext>({
+  name: string,
+  description?: string,
+  goal?: string,
+  ai: AiProvider,
+  context?: MyContext,
+  maxEngineIterations?: number,
+  compositionMode?: CompositionMode,
+  terms?: Term[],
+  guidelines?: Guideline[],
+  capabilities?: Capability[],
+  routes?: RouteOptions[],      // Can include nested guidelines
+  observations?: ObservationOptions[]  // Can reference routes by title
+});
+```
+
+**Made with ❤️ for the community**

package/docs/CONTRIBUTING.md

@@ -0,0 +1,481 @@
+# Contributing to @falai/agent
+
+First off, thank you for considering contributing to @falai/agent! 🎉
+
+It's people like you that make @falai/agent such a great tool for building AI agents.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Style Guidelines](#style-guidelines)
+- [Commit Guidelines](#commit-guidelines)
+- [Pull Request Process](#pull-request-process)
+
+---
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. We pledge to make participation in our project a harassment-free experience for everyone.
+
+### Our Standards
+
+**Positive behavior includes:**
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Unacceptable behavior includes:**
+
+- Harassment, trolling, or insulting/derogatory comments
+- Public or private harassment
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+---
+
+## How Can I Contribute?
+
+### 🐛 Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates.
+
+**When submitting a bug report, include:**
+
+- A clear and descriptive title
+- Steps to reproduce the behavior
+- Expected vs actual behavior
+- Code samples or test cases
+- Your environment (Node/Bun version, OS, TypeScript version)
+- Screenshots if applicable
+
+**Template:**
+
+```markdown
+**Description**
+A clear description of the bug.
+
+**To Reproduce**
+
+1. Create an agent with '...'
+2. Call method '...'
+3. See error
+
+**Expected Behavior**
+What you expected to happen.
+
+**Actual Behavior**
+What actually happened.
+
+**Environment**
+
+- Node/Bun version:
+- TypeScript version:
+- @falai/agent version:
+- OS:
+
+**Additional Context**
+Any other relevant information.
+```
+
+### 💡 Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues.
+
+**When suggesting an enhancement, include:**
+
+- A clear and descriptive title
+- The current behavior vs proposed behavior
+- Why this enhancement would be useful
+- Examples of how it would work
+- Potential implementation approach (optional)
+
+### 📝 Documentation Improvements
+
+Documentation is crucial! Feel free to:
+
+- Fix typos or unclear wording
+- Add examples
+- Improve API documentation
+- Create tutorials or guides
+- Translate documentation
+
+### 🔨 Code Contributions
+
+Want to add a feature or fix a bug? Great!
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js 18+** or **Bun 1.0+**
+- **Git**
+- **TypeScript knowledge**
+- Familiarity with AI/LLM concepts (helpful but not required)
+
+### Fork & Clone
+
+```bash
+# Fork the repository on GitHub, then:
+git clone https://github.com/YOUR_USERNAME/falai.git
+cd falai
+
+# Add upstream remote
+git remote add upstream https://github.com/gusnips/falai.git
+```
+
+### Install Dependencies
+
+```bash
+# Using bun (recommended)
+bun install
+
+# Or using npm
+npm install
+```
+
+### Set Up Development Environment
+
+```bash
+# Create .env file
+echo "GEMINI_API_KEY=your_test_key_here" > .env
+
+# Build the project
+bun run build
+
+# Run type checking
+bun typecheck
+
+# Run linting
+bun lint
+```
+
+---
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+# Update your main branch
+git checkout main
+git pull upstream main
+
+# Create a feature branch
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/issue-description
+```
+
+**Branch naming conventions:**
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation only
+- `refactor/` - Code refactoring
+- `test/` - Adding tests
+- `chore/` - Maintenance tasks
+
+### 2. Make Your Changes
+
+#### Project Structure
+
+```
+src/
+├── types/          # Type definitions
+├── core/           # Core classes (Agent, Route, etc.)
+├── providers/      # AI provider implementations
+├── utils/          # Utility functions
+├── constants/      # Constants
+└── index.ts        # Public exports
+```
+
+#### Key Principles
+
+- **DRY** - Don't Repeat Yourself
+- **Modular** - Keep code organized and reusable
+- **Type-Safe** - Use TypeScript properly
+- **Tested** - Add tests for new features
+- **Documented** - Update docs for public APIs
+
+### 3. Write Tests
+
+```bash
+# Run tests (when implemented)
+bun test
+
+# Run tests in watch mode
+bun test --watch
+```
+
+**Test Guidelines:**
+
+- Unit tests for individual functions
+- Integration tests for features
+- Add tests before fixing bugs
+- Aim for >80% coverage
+
+### 4. Check Your Code
+
+```bash
+# Type checking
+bun typecheck
+
+# Linting
+bun lint
+
+# Fix linting issues automatically
+bun lint:fix
+
+# Build to ensure no errors
+bun run build
+```
+
+### 5. Commit Your Changes
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+git add .
+git commit -m "feat: add disambiguation support for routes"
+```
+
+**Commit types:**
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `style:` - Code style changes (formatting, etc.)
+- `refactor:` - Code refactoring
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks
+
+**Examples:**
+
+```bash
+git commit -m "feat: add retry logic to AI provider"
+git commit -m "fix: resolve route reference memory leak"
+git commit -m "docs: update API reference for Agent class"
+git commit -m "refactor: simplify prompt builder logic"
+```
+
+### 6. Push and Create PR
+
+```bash
+# Push your branch
+git push origin feature/your-feature-name
+
+# Create a Pull Request on GitHub
+```
+
+---
+
+## Style Guidelines
+
+### TypeScript Style
+
+```typescript
+// ✅ Good
+interface UserContext {
+  userId: string;
+  userName: string;
+}
+
+const agent = new Agent<UserContext>({
+  name: "SupportBot",
+  ai: provider,
+});
+
+// ❌ Bad
+interface user_context {
+  user_id: string;
+  user_name: string;
+}
+
+const agent = new Agent<any>({
+  name: "SupportBot",
+  ai: provider,
+});
+```
+
+### Code Style
+
+- **Use TypeScript** - No `any` types unless absolutely necessary
+- **camelCase** for variables and functions
+- **PascalCase** for classes and interfaces
+- **UPPER_SNAKE_CASE** for constants
+- **Explicit return types** for public APIs
+- **JSDoc comments** for public methods
+- **No console.log** in production code (use proper logging)
+
+### File Organization
+
+```typescript
+/**
+ * Brief description of the file
+ */
+
+// Imports - group by: external, internal types, internal code
+import { ExternalLib } from "external-lib";
+import type { MyType } from "@/types/mytype";
+import { MyClass } from "@/core/MyClass";
+
+// Constants
+const DEFAULT_VALUE = 10;
+
+// Types (if not in types/)
+interface LocalType {
+  // ...
+}
+
+// Main code
+export class MyClass {
+  // ...
+}
+```
+
+### Documentation Style
+
+````typescript
+/**
+ * Creates a new agent with the specified configuration.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   name: "MyBot",
+ *   ai: provider,
+ * });
+ * ```
+ *
+ * @param options - Configuration options for the agent
+ * @returns A new Agent instance
+ */
+export class Agent<TContext = unknown> {
+  constructor(options: AgentOptions<TContext>) {
+    // ...
+  }
+}
+````
+
+---
+
+## Commit Guidelines
+
+### Commit Message Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Example:**
+
+```
+feat(agent): add support for custom AI providers
+
+- Implement AiProvider interface
+- Add OpenAI provider example
+- Update documentation
+
+Closes #123
+```
+
+### Scopes
+
+- `agent` - Agent core
+- `route` - Route/Journey DSL
+- `tools` - Tool system
+- `types` - Type definitions
+- `providers` - AI providers
+- `docs` - Documentation
+- `examples` - Example files
+
+---
+
+## Pull Request Process
+
+### Before Submitting
+
+- [ ] Code compiles without errors (`bun run build`)
+- [ ] All tests pass (`bun test`)
+- [ ] Linting passes (`bun lint`)
+- [ ] Type checking passes (`bun typecheck`)
+- [ ] Documentation updated (if needed)
+- [ ] Examples added (if new feature)
+- [ ] CHANGELOG updated (for significant changes)
+
+### PR Template
+
+```markdown
+## Description
+
+Brief description of changes.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## How Has This Been Tested?
+
+Describe the tests you ran.
+
+## Checklist
+
+- [ ] My code follows the style guidelines
+- [ ] I have performed a self-review
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+
+## Related Issues
+
+Closes #(issue number)
+```
+
+### Review Process
+
+1. **Automated Checks** - CI must pass
+2. **Code Review** - At least one maintainer approval required
+3. **Testing** - Reviewers may test your changes
+4. **Discussion** - Address feedback and questions
+5. **Merge** - Once approved, maintainers will merge
+
+---
+
+## Questions?
+
+- 💬 Open a [Discussion](https://github.com/gusnips/falai/discussions)
+- 🐛 Report an [Issue](https://github.com/gusnips/falai/issues)
+- 📧 Email: (if you want to add your email)
+
+---
+
+## Recognition
+
+Contributors will be:
+
+- Listed in our README
+- Mentioned in release notes
+- Part of our growing community! 🎉
+
+---
+
+**Thank you for contributing to @falai/agent!**
+
+Made with ❤️ for the community