@falai/agent 0.8.1 → 0.9.0-alpha-1

package/dist/src/utils/template.js

@@ -0,0 +1,276 @@
+/**
+ * Renders a template, which can be a string or a function, using the provided context.
+ * This function is asynchronous to support template functions that perform async operations.
+ *
+ * @param template - The template to render (string or function).
+ * @param params - The context object to pass to the template function.
+ * @returns A promise that resolves to the rendered string.
+ *
+ * @example
+ * ```typescript
+ * // With a string template
+ * const result1 = await render("Hello {{name}}", { context: { name: "Alice" } });
+ * // Result: "Hello Alice"
+ *
+ * // With a function template
+ * const fnTemplate = ({ context }) => `Hello ${context.name}`;
+ * const result2 = await render(fnTemplate, { context: { name: "Bob" } });
+ * // Result: "Hello Bob"
+ * ```
+ */
+export async function render(template, params) {
+    if (typeof template === "function") {
+        // Execute the function and await the result if it's a promise
+        const result = await Promise.resolve(template(params));
+        return result;
+    }
+    if (typeof template === "string") {
+        // Fallback to the old renderTemplate logic for string-based templates
+        return renderTemplate(template, params.context);
+    }
+    // Return empty string if template is undefined or not a supported type
+    return "";
+}
+/**
+ * Renders an array of templates.
+ *
+ * @param templates - An array of templates to render.
+ * @param params - The context object.
+ * @returns A promise that resolves to an array of rendered strings.
+ */
+export async function renderMany(templates, params) {
+    if (!templates) {
+        return [];
+    }
+    return Promise.all(templates.map((t) => render(t, params)));
+}
+/**
+ * @deprecated Use the asynchronous `render` function instead.
+ * Renders template variables in a string using the provided context.
+ * Supports {{variable}} and {{object.property}} syntax for property access.
+ *
+ * @param template - The template string containing {{variable}} placeholders
+ * @param context - The context object to pull values from
+ * @returns The rendered string with variables replaced
+ *
+ * @example
+ * ```typescript
+ * const template = "Hello {{user.name}}, welcome to {{company.name}}!";
+ * const context = {
+ *   user: { name: "Alice", age: 30 },
+ *   company: { name: "Acme Corp", location: "NYC" }
+ * };
+ * const result = renderTemplate(template, context);
+ * // Result: "Hello Alice, welcome to Acme Corp!"
+ *
+ * // Array handling
+ * const template2 = "Items: {{items}}";
+ * const context2 = { items: ["apple", "banana", "cherry"] };
+ * const result2 = renderTemplate(template2, context2);
+ * // Result: "Items: apple, banana, cherry"
+ * ```
+ */
+export function renderTemplate(template, context) {
+    if (!template || !context) {
+        return template;
+    }
+    return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+        const value = getValueByPath(context, path.trim());
+        if (value === undefined || value === null) {
+            return match; // Keep the original placeholder if value not found
+        }
+        return valueToString(value);
+    });
+}
+/**
+ * Gets a value from an object using dot notation path.
+ * Supports nested property access like "user.name" or "user.address.city".
+ *
+ * @param obj - The object to search in
+ * @param path - The dot-separated path to the property
+ * @returns The value at the path, or undefined if not found
+ */
+function getValueByPath(obj, path) {
+    const keys = path.split(".");
+    let current = obj;
+    for (const key of keys) {
+        if (current === null ||
+            current === undefined ||
+            typeof current !== "object") {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Converts a value to its string representation for template rendering.
+ * Handles different types appropriately.
+ *
+ * @param value - The value to convert to string
+ * @returns String representation of the value
+ */
+function valueToString(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        // For arrays, join with commas by default
+        // Users can override this by using JSON.stringify in their templates if needed
+        return value.map((item) => valueToString(item)).join(", ");
+    }
+    if (typeof value === "object") {
+        // For objects, convert to JSON string
+        // This provides a readable representation while being safe
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return "[object Object]";
+        }
+    }
+    // Fallback for any other type
+    return JSON.stringify(value);
+}
+/**
+ * @deprecated This function does not support async template functions.
+ * Renders template variables in an object recursively.
+ * Handles nested objects and arrays.
+ *
+ * @param obj - The object to render templates in
+ * @param context - The context object to pull values from
+ * @returns The object with all string templates rendered
+ */
+export function renderTemplateObject(obj, context) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (typeof obj === "string") {
+        return renderTemplate(obj, context);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => renderTemplateObject(item, context));
+    }
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = renderTemplateObject(value, context);
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Formats a JSON structure into readable markdown format.
+ * Handles nested objects, arrays, and primitive values.
+ *
+ * @param data - The JSON data to format
+ * @param title - Optional title for the knowledge base section
+ * @param maxDepth - Maximum nesting depth (default: 3)
+ * @returns Formatted markdown string
+ *
+ * @example
+ * ```typescript
+ * const knowledge = {
+ *   company: {
+ *     name: "Acme Corp",
+ *     products: ["Widget A", "Widget B"],
+ *     locations: {
+ *       headquarters: "NYC",
+ *       branches: ["LA", "Chicago"]
+ *     }
+ *   }
+ * };
+ *
+ * const markdown = formatKnowledgeBase(knowledge, "Company Information");
+ * // Output:
+ * // ## Company Information
+ * //
+ * // ### company
+ * // - **name**: Acme Corp
+ * // - **products**:
+ * //   - Widget A
+ * //   - Widget B
+ * // - **locations**:
+ * //   - **headquarters**: NYC
+ * //   - **branches**:
+ * //     - LA
+ * //     - Chicago
+ * ```
+ */
+export function formatKnowledgeBase(data, title, maxDepth = 3) {
+    const lines = [];
+    if (title) {
+        lines.push(`## ${title}`);
+        lines.push("");
+    }
+    if (!data || typeof data !== "object") {
+        lines.push("*No knowledge base data available*");
+        return lines.join("\n");
+    }
+    formatObject(data, lines, 0, maxDepth);
+    return lines.join("\n");
+}
+/**
+ * Recursively formats an object into markdown format
+ */
+function formatObject(obj, lines, depth, maxDepth, prefix = "") {
+    const entries = Object.entries(obj);
+    if (entries.length === 0) {
+        lines.push(`${prefix}*Empty*`);
+        return;
+    }
+    for (const [key, value] of entries) {
+        const currentPrefix = prefix ? `${prefix}  ` : "";
+        if (value === null || value === undefined) {
+            lines.push(`${currentPrefix}- **${key}**: *Not specified*`);
+        }
+        else if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            lines.push(`${currentPrefix}- **${key}**: ${value}`);
+        }
+        else if (Array.isArray(value)) {
+            if (value.length === 0) {
+                lines.push(`${currentPrefix}- **${key}**: *Empty list*`);
+            }
+            else {
+                lines.push(`${currentPrefix}- **${key}**:`);
+                for (const item of value) {
+                    if (typeof item === "string" ||
+                        typeof item === "number" ||
+                        typeof item === "boolean") {
+                        lines.push(`${currentPrefix}  - ${item}`);
+                    }
+                    else if (depth < maxDepth &&
+                        typeof item === "object" &&
+                        item !== null) {
+                        lines.push(`${currentPrefix}  - ${JSON.stringify(item)}`);
+                    }
+                    else {
+                        lines.push(`${currentPrefix}  - ${JSON.stringify(item)}`);
+                    }
+                }
+            }
+        }
+        else if (typeof value === "object") {
+            if (depth < maxDepth) {
+                lines.push(`${currentPrefix}- **${key}**:`);
+                formatObject(value, lines, depth + 1, maxDepth, currentPrefix);
+            }
+            else {
+                lines.push(`${currentPrefix}- **${key}**: ${JSON.stringify(value)}`);
+            }
+        }
+        else {
+            lines.push(`${currentPrefix}- **${key}**: ${JSON.stringify(value)}`);
+        }
+    }
+}
+//# sourceMappingURL=template.js.map

package/dist/src/utils/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/utils/template.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -1,113 +1,219 @@
-# Documentation
+# @falai/agent Documentation
 
-Welcome to the `@falai/agent` documentation!
+Welcome to the `@falai/agent` documentation! This comprehensive framework enables you to build sophisticated, type-safe conversational AI agents with **AI-powered routing**, **schema-driven data extraction**, and **declarative conversation flows**.
 
-📋 **[Complete Documentation Index →](DOCS.md)** - Full searchable index of all docs
+## ✨ What Makes @falai/agent Unique
+
+- 🤖 **AI-Powered Routing**: Intelligent route and step selection based on conversation context and user intent
+- 🎯 **Schema-First Data Collection**: Type-safe, structured data extraction from natural conversations
+- 🔀 **Route DSL**: Fluent, composable API for building complex multi-step conversation flows
+- 🏗️ **Type-Safe Context**: Generic context management with lifecycle hooks and dynamic providers
+- 🔄 **Streaming & Tools**: Real-time streaming responses with dynamic tool execution
+- 💾 **Comprehensive Persistence**: Database-agnostic session and message storage across multiple adapters
 
 ## 📖 Documentation Structure
 
-### Getting Started
+### 🚀 Getting Started
+
+- **[Quick Start Guide](./guides/getting-started/README.md)** - Build your first agent in 15 minutes
+
+### 🏗️ Core Framework
+
+#### Agent Architecture
 
-- **[Getting Started Guide](./GETTING_STARTED.md)** - Build your first agent in 5 minutes
+- **[Agent Overview](./core/agent/README.md)** - Agent lifecycle, configuration & hooks
+- **[Context Management](./core/agent/context-management.md)** - Dynamic context providers & updates
+- **[Session Management](./core/agent/session-management.md)** - Session persistence & state
 
-### Core Concepts
+#### AI Routing System
 
-- **[Architecture](./ARCHITECTURE.md)** - Design principles & philosophy (Data-driven sessions) ⭐ **UPDATED**
-- **[Agent](./AGENT.md)** - Comprehensive guide to declarative vs fluent configuration ⭐ **UPDATED**
-- **[Context Management](./CONTEXT_MANAGEMENT.md)** - Session step & data extraction patterns ⭐ **UPDATED**
+- **[Intelligent Routing](./core/routing/intelligent-routing.md)** - AI-powered route and step selection
+- **[Route DSL](./core/conversation-flows/route-dsl.md)** - Declarative conversation flow design
+- **[Step Transitions](./core/conversation-flows/step-transitions.md)** - Conditional logic and branching
 
-### Conversational Flows
+#### Conversation Flows
 
-- **[Routes Guide](./ROUTES.md)** - Complete guide to creating and managing conversational routes ⭐ **NEW**
-- **[Steps Guide](./STEPS.md)** - Complete guide to creating and managing steps ⭐ **NEW**
+- **[Routes](./core/conversation-flows/routes.md)** - Route definition, lifecycle & completion
+- **[Steps](./core/conversation-flows/steps.md)** - Step configuration, data collection & validation
+- **[Data Collection](./core/conversation-flows/data-collection.md)** - Schema-driven data extraction
 
-### Reference
+#### AI Integration
 
-- **[API Reference](./API_REFERENCE.md)** - Complete API documentation for all classes, methods, and types
-- **[AI Providers Guide](./PROVIDERS.md)** - Gemini, OpenAI, Anthropic, and custom providers
-- **[Domain Organization](./DOMAINS.md)** - Optional tool security & organization
-- **[Persistence Guide](./PERSISTENCE.md)** - Auto-save sessions and messages to any database
-- **[Database Adapters](./ADAPTERS.md)** - Adapter comparison and configuration examples
+- **[AI Providers](./core/ai-integration/providers.md)** - Gemini, OpenAI, Anthropic, OpenRouter
+- **[Prompt Composition](./core/ai-integration/prompt-composition.md)** - How prompts are built with context
+- **[Response Processing](./core/ai-integration/response-processing.md)** - Schema extraction & tool calls
 
-### Contributing
+#### Tools & Execution
 
-- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to the project
-- **[Publishing Guide](./PUBLISHING.md)** - How to publish updates to npm
+- **[Tool Definition](./core/tools/tool-definition.md)** - Creating and configuring tools
+- **[Tool Execution](./core/tools/tool-execution.md)** - Dynamic tool calling and context updates
+- **[Tool Scoping](./core/tools/tool-scoping.md)** - Agent, route, and step-level tool management
+
+#### Persistence
+
+- **[Session Storage](./core/persistence/session-storage.md)** - Session persistence patterns
+- **[Database Adapters](./core/persistence/adapters.md)** - Built-in adapter configurations
+
+### 🚀 Advanced Guides
+
+- **[Building Agents](./guides/building-agents/)** - Complete agent construction patterns
+- **[Advanced Patterns](./guides/advanced-patterns/)** - Complex use cases & integrations
+- **[API Reference](./api/README.md)** - Complete API documentation
 
 ## 🎯 Quick Links
 
-### By Use Case
+### By Learning Path
 
-**First time here?**
-→ Start with [Getting Started](./GETTING_STARTED.md)
+**🚀 First time here?**
+→ Start with [Quick Start Guide](./guides/getting-started/README.md)
 
-**Understanding the design?**
-→ Read [Architecture Guide](./ARCHITECTURE.md)
+**🏗️ Understanding the design?**
+→ Read [Agent Overview](./core/agent/README.md) then [Intelligent Routing](./core/routing/intelligent-routing.md)
 
-**Building a complex agent?**
-→ Check [Agent](./AGENT.md)
+**🤖 Building AI-powered conversations?**
+→ See [Route DSL](./core/conversation-flows/route-dsl.md), [Intelligent Routing](./core/routing/intelligent-routing.md), and [Step Transitions](./core/conversation-flows/step-transitions.md)
 
-**Creating conversational flows?**
-→ See [Routes Guide](./ROUTES.md) and [Steps Guide](./STEPS.md)
+**🎯 Collecting structured data?**
+→ Learn [Data Collection](./core/conversation-flows/data-collection.md) and [Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)
 
-**Need tool security?**
-→ See [Domain Organization](./DOMAINS.md)
+**🔧 Working with tools?**
+→ See [Tool Definition](./core/tools/tool-definition.md), [Tool Execution](./core/tools/tool-execution.md), and [Tool Scoping](./core/tools/tool-scoping.md)
 
-**Need specific API details?**
-→ Browse the [API Reference](./API_REFERENCE.md)
+**💾 Need persistence?**
+→ See [Session Storage](./core/persistence/session-storage.md) and [Database Adapters](./core/persistence/adapters.md)
 
-**Need persistence?**
-→ See [Persistence Guide](./PERSISTENCE.md)
+**🚀 Going to production?**
+→ Check [Server Deployment](../examples/integrations/server-deployment.ts) and [Advanced Patterns](./guides/advanced-patterns/)
 
 ### By Topic
 
-- **Architecture & Design**: [Architecture Guide](./ARCHITECTURE.md)
-- **Agent Configuration**: [Agent](./AGENT.md) | [Context Management](./CONTEXT_MANAGEMENT.md)
-- **Conversation Flows**: [Routes Guide](./ROUTES.md) | [Steps Guide](./STEPS.md) | [API Reference - Routes](./API_REFERENCE.md#route)
-- **Tools & Domains**: [Domain Organization](./DOMAINS.md) | [API Reference - Tools](./API_REFERENCE.md#definetool)
-- **AI Providers**: [Providers Guide](./PROVIDERS.md) | [API Reference](./API_REFERENCE.md#geminiprovider)
-- **Database Persistence**: [Persistence Guide](./PERSISTENCE.md) | [Adapters](./ADAPTERS.md)
-- **Contributing**: [Contributing Guide](./CONTRIBUTING.md) | [Publishing Guide](./PUBLISHING.md)
+- **Agent Architecture**: [Agent](./core/agent/README.md) | [Context](./core/agent/context-management.md) | [Sessions](./core/agent/session-management.md)
+- **AI Routing System**: [Intelligent Routing](./core/routing/intelligent-routing.md) | [Route DSL](./core/conversation-flows/route-dsl.md) | [Step Transitions](./core/conversation-flows/step-transitions.md)
+- **Conversation Flows**: [Routes](./core/conversation-flows/routes.md) | [Steps](./core/conversation-flows/steps.md) | [Data Collection](./core/conversation-flows/data-collection.md)
+- **AI Integration**: [Providers](./core/ai-integration/providers.md) | [Prompts](./core/ai-integration/prompt-composition.md) | [Responses](./core/ai-integration/response-processing.md)
+- **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Execution](./core/tools/tool-execution.md) | [Tool Scoping](./core/tools/tool-scoping.md)
+- **Persistence**: [Session Storage](./core/persistence/session-storage.md) | [Adapters](./core/persistence/adapters.md)
+- **Advanced**: [Building Agents](./guides/building-agents/) | [Patterns](./guides/advanced-patterns/) | [API Reference](./api/)
+
+## 💡 Examples by Domain
 
-## 💡 Examples
+Check out the [`examples/`](../examples/) directory for complete, runnable examples organized by architectural domain:
 
-Check out the [`examples/`](../examples/) directory for complete, runnable examples:
+### 🏗️ Core Concepts
 
-### Core Examples
+- **[Basic Agent](../examples/core-concepts/basic-agent.ts)** - Minimal agent setup and configuration
+- **[Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)** - Type-safe data collection with JSON Schema
+- **[Session Management](../examples/core-concepts/session-management.ts)** - Multi-turn conversations with persistence
+- **[Context Providers](../examples/core-concepts/context-providers.ts)** - Dynamic context fetching and updates
 
-- **[Declarative Agent](../examples/declarative-agent.ts)** - Full constructor-based configuration
-- **[Travel Agent](../examples/travel-agent.ts)** - Complex multi-route travel booking system
-- **[Healthcare Agent](../examples/healthcare-agent.ts)** - Full example
-- **[Streaming Agent](../examples/streaming-agent.ts)** - Real-time streaming responses
-- **[Company Q&A Agent](../examples/company-qna-agent.ts)** - Stepless question-answering with knowledge base
+### 🤖 AI Routing System
 
-### Persistence Examples
+- **[Simple Route](../examples/conversation-flows/simple-route.ts)** - Basic route with linear step progression
+- **[Multi-Route Agent](../examples/conversation-flows/multi-route-agent.ts)** - AI-powered route selection from multiple options
+- **[Data-Driven Flows](../examples/conversation-flows/data-driven-flows.ts)** - Conditional logic with skipIf and requires
+- **[Conditional Branching](../examples/conversation-flows/conditional-branching.ts)** - AI-powered branching decisions
+- **[Completion Transitions](../examples/conversation-flows/completion-transitions.ts)** - Automatic route transitions when flows complete
 
-- **[Prisma Persistence](../examples/prisma-persistence.ts)** - Auto-save with Prisma ORM
-- **[Redis Persistence](../examples/redis-persistence.ts)** - Fast in-memory persistence
+### 💬 Conversation Flows
 
-### Provider Examples
+- **[Knowledge-Based Agent](../examples/advanced-patterns/knowledge-based-agent.ts)** - Agents with domain-specific knowledge bases
+- **[Persistent Onboarding](../examples/advanced-patterns/persistent-onboarding.ts)** - Multi-step onboarding with data persistence
+- **[Behavioral Control](../examples/advanced-patterns/behavioral-control.ts)** - Guidelines and prohibitions for agent behavior
 
-- **[OpenAI Agent](../examples/openai-agent.ts)** - GPT-5 integration
-- **[Gemini Agent](../examples/gemini-agent.ts)** - Google Gemini integration
-- **[Anthropic Agent](../examples/healthcare-agent.ts)** - Claude 3.5 Sonnet
+### 🤖 AI Providers
 
-### Advanced Examples
+- **[OpenAI Integration](../examples/ai-providers/openai-integration.ts)** - GPT-4 and GPT-3.5 Turbo with backup models
+- **[Anthropic Integration](../examples/ai-providers/anthropic-integration.ts)** - Claude with streaming and tool calling
+- **[Custom Provider](../examples/ai-providers/custom-provider.ts)** - Build your own AI provider integration
 
-- **[Domain Scoping](../examples/domain-scoping.ts)** - Control tool access per route
-- **[Rules & Prohibitions](../examples/rules-prohibitions.ts)** - Fine-grained behavior control
-- **[Collected data Modification](../examples/data-data-modification.ts)** - Tools that validate and enrich collected data
+### 🔧 Tools & Execution
+
+- **[Basic Tools](../examples/tools/basic-tools.ts)** - Simple tool creation and execution
+- **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Tools that modify collected data
+- **[Context Updating Tools](../examples/tools/context-updating-tools.ts)** - Tools that modify agent context
+- **[Domain Scoped Tools](../examples/tools/domain-scoped-tools.ts)** - Tool security and access control
+
+### 💾 Persistence
+
+- **[Memory Sessions](../examples/persistence/memory-sessions.ts)** - In-memory session management
+- **[Redis Persistence](../examples/persistence/redis-persistence.ts)** - High-performance Redis storage
+- **[Database Persistence](../examples/persistence/database-persistence.ts)** - SQL/NoSQL database integration
+- **[Custom Adapter](../examples/persistence/custom-adapter.ts)** - Build custom persistence adapters
+
+### 🚀 Advanced Patterns
+
+- **[Multi-Turn Conversations](../examples/advanced-patterns/multi-turn-conversations.ts)** - Complex dialogue flows with backtracking
+- **[Streaming Responses](../examples/advanced-patterns/streaming-responses.ts)** - Real-time response streaming
+- **[Route Lifecycle Hooks](../examples/advanced-patterns/route-lifecycle-hooks.ts)** - Custom route behavior and data transformation
+
+### 🔗 Integrations
+
+- **[Server Deployment](../examples/integrations/server-deployment.ts)** - HTTP API with WebSocket streaming
+- **[Database Integration](../examples/integrations/database-integration.ts)** - Direct database access patterns
+- **[Healthcare Integration](../examples/integrations/healthcare-integration.ts)** - Domain-specific healthcare workflows
+- **[Search Integration](../examples/integrations/search-integration.ts)** - Integration with search engines
 
 ## 🤝 Contributing
 
-Found an error in the docs? Want to add examples? See our [**Contributing Guide**](./CONTRIBUTING.md) for:
+We welcome contributions to improve the documentation and examples! Here's how you can help:
+
+### Ways to Contribute
 
-- How to set up your development environment
-- Code style guidelines
-- Pull request process
-- Ways you can help
+- **📝 Improve Documentation** - Fix typos, clarify explanations, add examples
+- **🎯 Create Examples** - Add examples for new use cases or domains
+- **🔧 Update Code Samples** - Ensure examples work with latest framework versions
+- **📚 Write Guides** - Create tutorials for specific patterns or integrations
+- **🐛 Report Issues** - Found a bug in docs or examples? Let us know!
+
+### Getting Started
 
-We welcome all contributions - from typo fixes to new features!
+1. **Fork** the repository
+2. **Clone** your fork: `git clone https://github.com/your-username/agent.git`
+3. **Install** dependencies: `bun install`
+4. **Make changes** in the appropriate domain directory
+5. **Test examples** by running them: `bun run examples/your-example.ts`
+6. **Submit** a pull request
+
+### Documentation Structure
+
+When adding new content, follow the domain-focused organization:
+
+```
+docs/
+├── core/                    # Core framework docs
+│   ├── agent/              # Agent architecture & lifecycle
+│   ├── routing/            # AI routing system & intelligent selection
+│   ├── conversation-flows/ # Route DSL, steps, data collection
+│   ├── ai-integration/     # Providers, prompts, response processing
+│   ├── tools/              # Tool definition, execution, scoping
+│   └── persistence/        # Session storage & database adapters
+└── guides/                 # End-to-end guides
+    └── [guide-name]/       # getting-started, building-agents, etc.
+
+examples/
+├── core-concepts/          # Basic agent setup & fundamental concepts
+├── ai-providers/           # AI provider integrations
+├── conversation-flows/     # AI routing & conversation patterns
+├── persistence/            # Session storage implementations
+├── tools/                  # Tool creation & execution patterns
+├── advanced-patterns/      # Complex use cases & integrations
+└── integrations/           # External service integrations
+```
+
+### Example Contribution Workflow
+
+1. **Identify the domain** your example belongs to (e.g., `tools`, `persistence`)
+2. **Create the example** in the appropriate domain directory
+3. **Add comprehensive comments** explaining the concepts
+4. **Include error handling** and best practices
+5. **Update documentation** links if needed
+6. **Test thoroughly** before submitting
+
+### Need Help?
+
+- 📖 **[Contributing Guide](./CONTRIBUTING.md)** - Detailed contribution guidelines
+- 💬 **[Discussions](https://github.com/falai-dev/agent/discussions)** - Ask questions and get help
+- 🐛 **[Issues](https://github.com/falai-dev/agent/issues)** - Report bugs or request features
 
 ---