### Start Qdrant Server (Docker)

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Command to start a Qdrant server instance using Docker. This is a prerequisite for using the QdrantVectorStore.

```bash
docker run -p 6333:6333 qdrant/qdrant
```

--------------------------------

### Custom Tool Implementation Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

An example demonstrating how to implement the Tool trait for a custom tool, such as a weather tool. This includes defining the tool's name, description, parameters, and the core run logic.

```rust
use langchain_rust::tools::Tool;
use async_trait::async_trait;
use serde_json::{json, Value};
use std::error::Error;

struct WeatherTool;

#[async_trait]
impl Tool for WeatherTool {
    fn name(&self) -> String {
        "get_weather".to_string()
    }
    
    fn description(&self) -> String {
        "Get current weather for a city".to_string()
    }
    
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name"
                }
            },
            "required": ["city"]
        })
    }
    
    async fn run(&self, input: Value) -> Result<String, Box<dyn Error>> {
        let city = input["city"].as_str().ok_or("Missing city")?;
        // Call weather API
        Ok(format!("Weather in {}: Sunny, 72°F", city))
    }
}
```

--------------------------------

### Usage Example for prompt_args! Macro

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/07-prompts.md

Demonstrates how to use the prompt_args! macro to create a HashMap with specific input variables.

```rust
use langchain_rust::prompt_args;

let args = prompt_args! {
    "input" => "What is Rust?",
    "language" => "English",
    "format" => "brief",
};
```

--------------------------------

### OpenSearchVectorStore Setup

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Initializes the OpenSearchVectorStore with endpoint, index name, and region. Uses AWS SDK for authentication.

```rust
use langchain_rust::vectorstore::OpenSearchVectorStore;

let vs = OpenSearchVectorStore::new(
    "https://search-domain-hash.us-east-1.es.amazonaws.com".to_string(),
    "documents".to_string(),
    "us-east-1".to_string(),
).await?;
```

--------------------------------

### Ollama Embed Documents Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Example of how to instantiate OllamaEmbedder and embed a list of documents. Ensure Ollama is running locally.

```rust
use langchain_rust::embedding::OllamaEmbedder;

let embedder = OllamaEmbedder::new(
    "http://localhost:11434".to_string(),
    "nomic-embed-text".to_string(),
);

let docs = vec![
    "First document text".to_string(),
    "Second document text".to_string(),
];

let embeddings = embedder.embed_documents(&docs).await?;
```

--------------------------------

### Document Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/09-types-schemas.md

Demonstrates how to create and populate a Document instance with content, metadata, and a score. Shows accessing document fields.

```rust
use langchain_rust::schemas::Document;
use serde_json::json;

let mut metadata = HashMap::new();
metadata.insert("source".to_string(), json!("document.pdf"));
metadata.insert("page".to_string(), json!(1));

let doc = Document::new("Document content")
    .with_metadata(metadata)
    .with_score(0.95);

println!("Content: {}", doc.page_content);
println!("Source: {}", doc.metadata["source"]);
```

--------------------------------

### Usage Example for HtmlLoader

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Demonstrates how to use the HtmlLoader to load documents from an HTML file.

```rust
use langchain_rust::document_loaders::HtmlLoader;
use url::Url;
use futures_util::StreamExt;

let url = Url::parse("https://example.com/")?;
let loader = HtmlLoader::from_path("./page.html", url)?;

let documents = loader.load().await?.collect::<Vec<_>>().await;
```

--------------------------------

### DirLoader Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Shows how to create a DirLoader instance to load all text files with a '.txt' extension from the './documents' directory.

```rust
use langchain_rust::document_loaders::DirLoader;
use futures_util::StreamExt;

let loader = DirLoader::from_path("./documents")?
    .with_glob_pattern("*.txt");

let documents = loader.load().await?
    .collect::<Vec<_>>()
    .await;
```

--------------------------------

### FastEmbed Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Example of initializing FastEmbedder with a specific model and embedding documents and a query. This runs locally without API keys.

```rust
use langchain_rust::embedding::{FastEmbedder, FastEmbedModel};

let embedder = FastEmbedder::new(FastEmbedModel::BGBaseENV15).await?;

let documents = vec![
    "The quick brown fox jumps".to_string(),
    "A lazy dog sleeps".to_string(),
];

let embeddings = embedder.embed_documents(&documents).await?;
println!("Embedding dimension: {}", embeddings[0].len());

let query = embedder.embed_query("fast animals").await?;
```

--------------------------------

### TextLoader Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Shows how to create a `TextLoader` instance for a specific file and load all its documents into a `Vec<Document>`.

```rust
use langchain_rust::document_loaders::TextLoader;
use futures_util::StreamExt;

let loader = TextLoader::from_path("./document.txt")?;
let mut stream = loader.load().await?;

let documents: Vec<Document> = stream
    .map(|r| r.unwrap())
    .collect()
    .await;
```

--------------------------------

### Ollama Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/02-llms.md

Initialize and use the Ollama LLM for local inference. This example shows how to set the model and base URL, then invoke the LLM with a prompt. Ensure Ollama is running and accessible at the specified URL.

```rust
use langchain_rust::llm::ollama::{Ollama, OllamaModel};

let llm = Ollama::default()
    .with_model("llama2")
    .with_base_url("http://localhost:11434");

let output = llm.invoke("Hello").await?;
```

--------------------------------

### Scraper Tool Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Demonstrates how to instantiate the Scraper tool and use its scrape method to fetch content from a URL.

```rust
use langchain_rust::tools::Scraper;

let scraper = Scraper::new();
let content = scraper.scrape("https://example.com").await?;
```

--------------------------------

### Usage Example for SequentialChain

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/01-chains.md

Demonstrates how to create and invoke a SequentialChain by adding individual chains and building the final sequential chain.

```rust
let chain1 = /* ... chain that produces "summary" ... */;
let chain2 = /* ... chain that takes "summary" as input ... */;

let sequential = SequentialChain::new()
    .add_chain("chain1", chain1)
    .add_chain("chain2", chain2)
    .build()?;

let result = sequential.invoke(prompt_args!("input" => "text")).await?;
```

--------------------------------

### Usage Example for HtmlToMarkdownLoader

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Shows how to configure and use the HtmlToMarkdownLoader with custom options to convert HTML to Markdown.

```rust
use langchain_rust::document_loaders::{HtmlToMarkdownLoader, HtmlToMarkdownOptions};
use url::Url;

let url = Url::parse("https://example.com/")?;
let options = HtmlToMarkdownOptions::default()
    .with_skip_tags(vec!["script".to_string(), "style".to_string()]);

let loader = HtmlToMarkdownLoader::from_path("./page.html", url, options)?;
let documents = loader.load().await?.collect::<Vec<_>>().await;
```

--------------------------------

### OpenAIEmbedder Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Shows how to instantiate and use the `OpenAIEmbedder` with a specific model like `text-embedding-3-small`. This example demonstrates embedding multiple documents and a query.

```rust
use langchain_rust::embedding::OpenAIEmbedder;

let embedder = OpenAIEmbedder::default()
    .with_model("text-embedding-3-small");

let docs = vec![
    "Rust is a systems programming language".to_string(),
    "Python is popular for data science".to_string(),
];

// let vectors = embedder.embed_documents(&docs).await?;
// println!("First document embedding: {:?}", vectors[0]);

// let query = embedder.embed_query("programming").await?;
// println!("Query vector length: {}", query.len());
```

--------------------------------

### Tool Selection Router Setup

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Illustrates setting up a SemanticRouter to map user input utterances to specific tool names, enabling dynamic tool selection.

```rust
// First route the input to select appropriate tool
let tool_router = SemanticRouter::new(embedder)
    .add_route(Route::new("search", "search_tool")
        .add_utterance("Find information about")
        .add_utterance("Search for"))
    .add_route(Route::new("calculate", "calc_tool")
        .add_utterance("What is")
        .add_utterance("Calculate"));

let handler = tool_router.route(user_input).await?;
// Then invoke the selected tool
```

--------------------------------

### TokenUsage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/02-llms.md

Demonstrates how to create TokenUsage instances and combine them using the sum method. Shows how to access the total_tokens field.

```rust
let usage = TokenUsage::new(100, 50);
println!("Used {} tokens", usage.total_tokens); // 150

let usage2 = TokenUsage::new(200, 75);
let combined = usage.sum(&usage2);
println!("Combined: {}", combined.total_tokens); // 425
```

--------------------------------

### SurrealDBVectorStore Setup

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Initializes the SurrealDBVectorStore with a database URL and table name. Supports WebSocket connections.

```rust
use langchain_rust::vectorstore::SurrealDBVectorStore;

let vs = SurrealDBVectorStore::new(
    "ws://localhost:8000".to_string(), // WebSocket connection
    "documents".to_string(),
).await?;
```

--------------------------------

### Build and Invoke an LLMChain with OpenAI

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/00-index.md

This example demonstrates how to set up an LLMChain using OpenAI's GPT-4o Mini model. It includes prompt formatting with system and human messages and invokes the chain with user input. Ensure you have the necessary API keys and dependencies configured.

```rust
use langchain_rust::
    chain::LLMChainBuilder,
    llm::openai::{OpenAI, OpenAIModel},
    prompt::HumanMessagePromptTemplate,
    message_formatter,
    fmt_message,
    fmt_template,
    Message,
    prompt_args,
};

#[tokio::main]
async fn main() {
    let llm = OpenAI::default()
        .with_model(OpenAIModel::Gpt4oMini.to_string());

    let prompt = message_formatter![
        fmt_message!(Message::new_system_message("You are helpful")),
        fmt_template!(HumanMessagePromptTemplate::new(
            template_fstring("{input}", "input")
        ))
    ];

    let chain = LLMChainBuilder::new()
        .prompt(prompt)
        .llm(llm)
        .build()
        .expect("Failed to build chain");

    let result = chain.invoke(prompt_args! {
        "input" => "What is Rust?"
    }).await.expect("Chain invocation failed");

    println!("Result: {}", result);
}
```

--------------------------------

### SQLDatabaseChain Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/01-chains.md

Demonstrates how to build and invoke a SQLDatabaseChain to translate a natural language question into a SQL query and execute it.

```rust
let chain = SQLDatabaseChainBuilder::new()
    .llm(openai)
    .database_uri("postgres://user:pass@localhost/db")
    .build()?;

let result = chain.invoke(prompt_args!(
    "input" => "How many users registered last month?"
)).await?;
```

--------------------------------

### Using PGVectorVectorStore

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Example of creating a PGVectorVectorStore, adding documents, and performing a similarity search. Ensure the database connection is valid and the `options` are correctly configured.

```rust
use langchain_rust::vectorstore::PGVectorVectorStore;

let vs = PGVectorVectorStore::new(
    "postgresql://user:pass@localhost/db".to_string(),
    "documents".to_string(),
).await?;

// Add documents
let docs = vec![
    Document::new("First document text"),
    Document::new("Second document text"),
];
let ids = vs.add_documents(&docs, &options).await?;

// Search
let results = vs.similarity_search(
    "search query",
    5,
    &options,
).await?;
```

--------------------------------

### OpenAI LLM Usage Examples

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/02-llms.md

Demonstrates how to instantiate and use the OpenAI LLM for text generation, simple invocation, and streaming responses. Requires API key configuration.

```rust
use langchain_rust::llm::openai::{OpenAI, OpenAIModel};
use langchain_rust::language_models::llm::LLM;
use langchain_rust::llm::Message;
use langchain_rust::llm::OpenAIConfig;

// Simple usage with default config
let llm = OpenAI::default()
    .with_model(OpenAIModel::Gpt4oMini.to_string());

// With custom API key
let llm = OpenAI::default()
    .with_config(OpenAIConfig::default().with_api_key("sk-..."))
    .with_model(OpenAIModel::Gpt4.to_string());

// Generate from messages
let result = llm.generate(&[
    Message::new_system_message("You are helpful"),
    Message::new_human_message("What is AI?"),
]).await?;
println!("Output: {}", result.generation);
println!("Tokens: {}", result.tokens.unwrap().total_tokens);

// Simple invoke
let output = llm.invoke("Explain quantum computing").await?;

// With streaming
let mut stream = llm.stream(&[
    Message::new_human_message("Write a poem")
]).await?;

while let Some(chunk) = stream.next().await {
    match chunk {
        Ok(data) => print!("{}", data.content),
        Err(e) => eprintln!("Error: {}", e),
    }
}
```

--------------------------------

### Quick Start Conversational Chain with OpenAI

Source: https://github.com/abraxas-365/langchain-rust/blob/main/README.md

Demonstrates initializing an OpenAI LLM, invoking it directly, and then setting up and invoking a conversational chain with a system message and prompt template. Handles potential errors during invocation.

```rust
use langchain_rust::chain::{Chain, LLMChainBuilder};
use langchain_rust::{fmt_message, fmt_placeholder, fmt_template,
    language_models::llm::LLM,
    llm::openai::{OpenAI, OpenAIModel},
    message_formatter,
    prompt::HumanMessagePromptTemplate,
    prompt_args,
    schemas::messages::Message,
    template_fstring,
};

#[tokio::main]
async fn main() {
    //We can then initialize the model:
    // If you'd prefer not to set an environment variable you can pass the key in directly via the `openai_api_key` named parameter when initiating the OpenAI LLM class:
    // let open_ai = OpenAI::default()
    //     .with_config(
    //         OpenAIConfig::default()
    //             .with_api_key("<your_key>"),
    //     ).with_model(OpenAIModel::Gpt4oMini.to_string());
    let open_ai = OpenAI::default().with_model(OpenAIModel::Gpt4oMini.to_string());


    //Once you've installed and initialized the LLM of your choice, we can try using it! Let's ask it what LangSmith is - this is something that wasn't present in the training data so it shouldn't have a very good response.
    let resp = open_ai.invoke("What is rust").await.unwrap();
    println!("{}", resp);

    // We can also guide it's response with a prompt template. Prompt templates are used to convert raw user input to a better input to the LLM.
    let prompt = message_formatter![
        fmt_message!(Message::new_system_message(
            "You are world class technical documentation writer."
        )),
        fmt_template!(HumanMessagePromptTemplate::new(template_fstring!(
            "{input}", "input"
        )))
    ];

    //We can now combine these into a simple LLM chain:

    let chain = LLMChainBuilder::new()
        .prompt(prompt)
        .llm(open_ai.clone())
        .build()
        .unwrap();

    //We can now invoke it and ask the same question. It still won't know the answer, but it should respond in a more proper tone for a technical writer!

    match chain
        .invoke(prompt_args! {
        "input" => "Quien es el escritor de 20000 millas de viaje submarino",
           })
        .await
    {
        Ok(result) => {
            println!("Result: {:?}", result);
        }
        Err(e) => panic!("Error invoking LLMChain: {:?}", e),
    }

    //If you want to prompt to have a list of messages you could use the `fmt_placeholder` macro

    let prompt = message_formatter![
        fmt_message!(Message::new_system_message(
            "You are world class technical documentation writer."
        )),
        fmt_placeholder!("history"),
        fmt_template!(HumanMessagePromptTemplate::new(template_fstring!(
            "{input}", "input"
        ))),
    ];

    let chain = LLMChainBuilder::new()
        .prompt(prompt)
        .llm(open_ai)
        .build()
        .unwrap();
    match chain
        .invoke(prompt_args! {
        "input" => "Who is the writer of 20,000 Leagues Under the Sea, and what is my name?",
        "history" => vec![
                Message::new_human_message("My name is: luis"),
                Message::new_ai_message("Hi luis"),
                ],

        })
        .await
    {
        Ok(result) => {
            println!("Result: {:?}", result);
        }
        Err(e) => panic!("Error invoking LLMChain: {:?}", e),
    }
}
```

--------------------------------

### Usage Example for HumanMessagePromptTemplate

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/07-prompts.md

Shows how to instantiate a HumanMessagePromptTemplate with an f-string style template.

```rust
use langchain_rust::{
    prompt::HumanMessagePromptTemplate,
    template_fstring,
};

let template = HumanMessagePromptTemplate::new(
    template_fstring("{input}", "input")
);
```

--------------------------------

### Build OpenAIToolsAgent

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Example of how to instantiate and build an OpenAIToolsAgent using the builder pattern. Requires tools and an LLM.

```rust
use langchain_rust::agent::open_ai_tools::OpenAIToolsAgentBuilder;

let agent = OpenAIToolsAgentBuilder::new()
    .tools(&[tool1, tool2])
    .system_message("You are a helpful assistant with access to tools")
    .build(llm)?;
```

--------------------------------

### Add langchain-rust with Qdrant Feature

Source: https://github.com/abraxas-365/langchain-rust/blob/main/README.md

Install `langchain-rust` with the `qdrant` feature enabled.

```bash
cargo add langchain-rust --features qdrant
```

--------------------------------

### Build ConversationalAgent Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Demonstrates how to instantiate a ConversationalAgent using its builder. This involves providing the LLM and a list of tools.

```rust
use langchain_rust::{
    agent::chat::ConversationalAgentBuilder,
    tools::Tool,
};
use std::sync::Arc;

let calculator = /* Arc<dyn Tool> */;
let search = /* Arc<dyn Tool> */;

let agent = ConversationalAgentBuilder::new()
    .tools(&[calculator, search])
    .build(llm)?;
```

--------------------------------

### Usage Example for PdfExtractLoader

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Demonstrates how to use PdfExtractLoader to load documents from a PDF file and collect them.

```rust
use langchain_rust::document_loaders::PdfExtractLoader;
use futures_util::StreamExt;

let loader = PdfExtractLoader::from_path("./document.pdf")?;
let mut stream = loader.load().await?;

let documents: Vec<Document> = stream
    .map(|r| r.unwrap())
    .collect()
    .await;

println!("Extracted {} pages", documents.len());
```

--------------------------------

### SourceCodeLoader Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Demonstrates how to initialize and use SourceCodeLoader with custom directory options to load Rust files, excluding the 'target' directory.

```rust
use langchain_rust::document_loaders::{SourceCodeLoader, DirLoaderOptions};
use futures_util::StreamExt;

let options = DirLoaderOptions {
    glob: None,
    suffixes: Some(vec!["rs".to_string()]),
    exclude: Some(vec!["target".to_string()]),
};

let loader = SourceCodeLoader::from_path("./src")?
    .with_dir_loader_options(options);

let documents = loader.load().await?
    .collect::<Vec<_>>()
    .await;
```

--------------------------------

### Add langchain-rust with Postgres Feature

Source: https://github.com/abraxas-365/langchain-rust/blob/main/README.md

Install `langchain-rust` with the `postgres` feature enabled.

```bash
cargo add langchain-rust --features postgres
```

--------------------------------

### Add langchain-rust with SurrealDB Feature

Source: https://github.com/abraxas-365/langchain-rust/blob/main/README.md

Install `langchain-rust` with the `surrealdb` feature enabled.

```bash
cargo add langchain-rust --features surrealdb
```

--------------------------------

### Semantic Routing Setup

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/00-index.md

Illustrates how to set up a semantic router with defined routes and utterances for intent recognition. The router can then be used to determine the appropriate handler for user input.

```rust
let router = SemanticRouter::new(embedder)
    .add_route(Route::new("sales", "handler")
        .add_utterance("How much does it cost?"))
    .add_route(Route::new("support", "handler")
        .add_utterance("I need help"));

if let Some(handler) = router.route(user_input).await? {
    // Route to appropriate handler
}
```

--------------------------------

### Usage Example for CsvLoader

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Demonstrates how to use CsvLoader to load documents from a CSV file, specifying the desired columns.

```rust
use langchain_rust::document_loaders::CsvLoader;
use futures_util::StreamExt;

let columns = vec![
    "name".to_string(),
    "age".to_string(),
    "city".to_string(),
];

let loader = CsvLoader::from_path("./data.csv", columns)?;
let mut stream = loader.load().await?;

let documents: Vec<Document> = stream
    .map(|r| r.unwrap())
    .collect()
    .await;
```

--------------------------------

### Usage Example - Static Routes

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Demonstrates how to create and use a SemanticRouter with statically defined routes. Ensure you have the necessary embedder (e.g., OpenAIEmbedder) and routes configured.

```rust
use langchain_rust::semantic_router::{SemanticRouter, Route};
use langchain_rust::embedding::OpenAIEmbedder;
use std::sync::Arc;

let embedder = Arc::new(OpenAIEmbedder::default());

let sales_route = Route::new("sales", "sales_handler")
    .add_utterance("How much does it cost?")
    .add_utterance("What's the price?")
    .add_utterance("Do you have a discount?");

let support_route = Route::new("support", "support_handler")
    .add_utterance("I need help")
    .add_utterance("Something's broken")
    .add_utterance("How do I use this?");

let router = SemanticRouter::new(embedder)
    .add_route(sales_route)
    .add_route(support_route);

// Route input
if let Some(handler) = router.route("What is the cost?").await?
{
    println!("Route to: {}", handler); // Output: sales_handler
}
```

--------------------------------

### Usage Example - Dynamic Routes

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Demonstrates setting up and using a RouteLayer for dynamic routing. This requires both an LLM and an embedder. Routes are defined by descriptions rather than specific utterances.

```rust
use langchain_rust::semantic_router::route_layer::{RouteLayer, DynamicRoute};
use langchain_rust::embedding::OpenAIEmbedder;
use langchain_rust::llm::openai::{OpenAI, OpenAIModel};
use std::sync::Arc;

let llm = Box::new(
    OpenAI::default().with_model(OpenAIModel::Gpt4oMini.to_string())
);
let embedder = Arc::new(OpenAIEmbedder::default());

let sales = DynamicRoute {
    name: "sales".to_string(),
    description: "Questions about pricing, discounts, and purchases".to_string(),
    handler: "sales_team".to_string(),
};

let tech_support = DynamicRoute {
    name: "tech_support".to_string(),
    description: "Technical issues, bugs, and how-to questions".to_string(),
    handler: "tech_team".to_string(),
};

let router = RouteLayer::new(llm, embedder)
    .add_route(sales)
    .add_route(tech_support);

match router.route("The app crashes when I click save").await?
{
    Some(handler) => println!("Route to: {}", handler),
    None => println!("No matching route"),
}
```

--------------------------------

### Initialize and Configure AgentExecutor

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Example demonstrating how to create an AgentExecutor from an agent, configure maximum iterations, and attach conversation memory. The executor can be used as a Chain.

```rust
use langchain_rust::agent::{
    chat::ConversationalAgentBuilder,
    executor::AgentExecutor,
};
use langchain_rust::memory::SimpleMemory;

let agent = ConversationalAgentBuilder::new()
    .tools(&[tool1, tool2])
    .build(llm)?;

let memory = SimpleMemory::new();

let executor = AgentExecutor::from_agent(agent)
    .with_max_iterations(10)
    .with_memory(memory.into());

let result = executor.invoke(prompt_args!(
    "input" => "Use the calculator to compute 5 factorial"
)).await?;

println!("Result: {}", result);
```

--------------------------------

### Using the Generic Retriever

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Example of initializing a retriever with a vector store and custom options, then retrieving relevant documents based on a query. Ensure the `vector_store` and `custom_options` are properly defined elsewhere.

```rust
use langchain_rust::vectorstore::Retriever;

let retriever = Retriever::new(vector_store, 5)
    .with_options(custom_options);

let relevant_docs = retriever.get_relevant_documents("query text").await?;
for doc in relevant_docs {
    println!("Score: {}, Content: {}", doc.score, doc.page_content);
}
```

--------------------------------

### Invoke Chain Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/01-chains.md

Demonstrates how to invoke a chain with input arguments and print the resulting string output. Ensure the `chain` object is properly initialized and the `PromptArgs` are correctly formatted.

```rust
use langchain_rust::{Chain, PromptArgs, prompt_args};

let result = chain.invoke(prompt_args! {
    "input" => "What is Rust?"
}).await?;

println!("Result: {}", result);
```

--------------------------------

### LLMChain Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/01-chains.md

Demonstrates how to construct and invoke an LLMChain using the builder pattern. It sets up a prompt, an OpenAI LLM, and then executes the chain with input variables.

```rust
use langchain_rust::{
    chain::LLMChainBuilder,
    llm::openai::{OpenAI, OpenAIModel},
    prompt::HumanMessagePromptTemplate,
    message_formatter,
    fmt_message,
    fmt_template,
    template_fstring,
    Message,
};

let prompt = message_formatter![
    fmt_message!(Message::new_system_message("You are a helpful assistant")),
    fmt_template!(HumanMessagePromptTemplate::new(
        template_fstring("{input}", "input")
    ))
];

let llm = OpenAI::default().with_model(OpenAIModel::Gpt4oMini.to_string());

let chain = LLMChainBuilder::new()
    .prompt(prompt)
    .llm(llm)
    .output_key("output")
    .build()?;

let result = chain.invoke(prompt_args!("input" => "What is 2+2?")).await?;
println!("{}", result);
```

--------------------------------

### PandocLoader Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Demonstrates how to load documents from a DOCX file using the PandocLoader. Ensure the input format and file path are correctly specified.

```rust
use langchain_rust::document_loaders::{PandocLoader, InputFormat};
use futures_util::StreamExt;

let loader = PandocLoader::from_path(
    InputFormat::Docx.to_string(),
    "./document.docx",
).await?;

let documents = loader.load().await?
    .collect::<Vec<_>>()
    .await;
```

--------------------------------

### Custom Calculator Tool Implementation

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

An example implementation of the Tool trait for a calculator, demonstrating how to define name, description, parameters, and the run logic.

```rust
use langchain_rust::tools::Tool;
use async_trait::async_trait;
use serde_json::{json, Value};

struct CalculatorTool;

#[async_trait]
impl Tool for CalculatorTool {
    fn name(&self) -> String {
        "calculator".to_string()
    }
    
    fn description(&self) -> String {
        "Perform mathematical calculations".to_string()
    }
    
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "Math expression to evaluate"
                }
            },
            "required": ["expression"]
        })
    }
    
    async fn run(&self, input: Value) -> Result<String, Box<dyn std::error::Error>> {
        let expr = input["expression"].as_str().ok_or("Missing expression")?;
        // Perform calculation
        Ok(format!("Result: {}", expr)) // Simplified
    }
}
```

--------------------------------

### Streaming LLM Response Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/02-llms.md

Demonstrates how to stream responses from an LLM and process them chunk by chunk. It collects the full response and prints each received content part.

```rust
use futures::StreamExt;

let mut stream = llm.stream(&[
    Message::new_human_message("Write a story about AI")
]).await?;

let mut full_response = String::new();
while let Some(result) = stream.next().await {
    match result {
        Ok(data) => {
            print!("{}", data.content);
            full_response.push_str(&data.content);
        }
        Err(e) => eprintln!("Stream error: {}", e),
    }
}
println!("\nFull response: {}", full_response);
```

--------------------------------

### Batch Processing Example for Large Datasets

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Illustrates how to process a large number of documents in batches to manage request sizes and token limits, using the chunks method.

```rust
let all_docs = vec![/* 10000 documents */];
let batch_size = 100;

for batch in all_docs.chunks(batch_size) {
    let embeddings = embedder.embed_documents(batch).await?;
    // Process batch embeddings
}
```

--------------------------------

### SimpleMemory Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/08-memory.md

Demonstrates how to create, add messages to, and access messages from a `SimpleMemory` instance. Shows adding user and AI messages, retrieving all messages, and formatting them as a string.

```rust
use langchain_rust::memory::SimpleMemory;

let memory = SimpleMemory::new();

// Add messages
memory.add_user_message("My name is Alice").await;
memory.add_ai_message("Hello Alice!").await;
memory.add_user_message("What's my name?").await;
memory.add_ai_message("Your name is Alice").await;

// Access messages
let messages = memory.messages();
println!("Total messages: {}", messages.len());

// Get formatted string
println!("History:\n{}", memory.to_string());
```

--------------------------------

### Add Documents and Search with SqliteVSSVectorStore

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Adds documents to the vector store and performs a similarity search. This example assumes `Document` and `add_documents!` macro are available.

```rust
use langchain_rust::vectorstore::SqliteVSSVectorStore;

let vs = SqliteVSSVectorStore::new(
    "./embeddings.db".to_string(),
    "vectors".to_string(),
).await?;

let docs = vec![
    Document::new("Sample text one"),
    Document::new("Sample text two"),
];

let ids = add_documents!(vs, &docs)?;
let results = similarity_search!(vs, "query", 5)?;
```

--------------------------------

### GitCommitLoader Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/06-document-loaders.md

Demonstrates how to load Git commit history and iterate through the documents. Each document's metadata contains commit details like hash, author, date, and message.

```rust
use langchain_rust::document_loaders::GitCommitLoader;
use futures_util::StreamExt;

let loader = GitCommitLoader::from_path("/path/to/repo")?;
let mut stream = loader.load().await?;

while let Some(Ok(doc)) = stream.next().await {
    println!("Commit: {}", doc.metadata.get("hash"));
    println!("Message: {}", doc.page_content);
}
```

--------------------------------

### End-to-End RAG Application Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/00-index.md

Demonstrates building a Retrieval-Augmented Generation (RAG) application. It involves loading PDF documents, creating embeddings, setting up a vector store and retriever, and finally building and invoking a Q&A chain.

```rust
use langchain_rust::{
    document_loaders::PdfExtractLoader,
    embedding::OpenAIEmbedder,
    vectorstore::Retriever,
    llm::openai::{OpenAI, OpenAIModel},
    chain::QAChainBuilder,
    prompt_args,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Load documents
    let loader = PdfExtractLoader::from_path("document.pdf")?;
    let docs = loader.load().await? 
        .collect::<Vec<_>>()
        .await
        .into_iter()
        .filter_map(|r| r.ok())
        .collect::<Vec<_>>();

    // 2. Create embedder and vector store
    let embedder = OpenAIEmbedder::default();
    let vs = /* initialize vector store */;
    let ids = vs.add_documents(&docs, &Default::default()).await?;

    // 3. Create retriever
    let retriever = Retriever::new(vs, 5);

    // 4. Build Q&A chain
    let llm = OpenAI::default()
        .with_model(OpenAIModel::Gpt4oMini.to_string());
    
    let chain = QAChainBuilder::new()
        .retriever(retriever)
        .llm(llm)
        .build()?;

    // 5. Answer questions
    let answer = chain.invoke(prompt_args! {
        "query" => "What is the main topic?"
    }).await?;

    println!("Answer: {}", answer);
    Ok(())
}
```

--------------------------------

### Creating a Reusable Code Review Prompt

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/07-prompts.md

Provides an example of creating a reusable prompt function that returns a boxed MessageFormatter. This prompt includes a system message and a template for code review.

```rust
pub fn create_code_review_prompt() -> Box<dyn MessageFormatter> {
    Box::new(message_formatter![
        fmt_message!(Message::new_system_message(
            "You are an expert code reviewer."
        )),
        fmt_template!(HumanMessagePromptTemplate::new(
            template_fstring!("Review this code:\n{code}", "code")
        )),
    ])
}
```

--------------------------------

### Initialize and Use SQL Query Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Demonstrates initializing the SQLQuery tool with a database connection string and integrating it into a ConversationalAgent. Allows execution of SQL queries against a database.

```rust
pub struct SQLQuery {
    connection_string: String,
}

impl SQLQuery {
    pub fn new(connection_string: String) -> Self;
    pub async fn run(&self, query: &str) -> Result<String, Box<dyn Error>>;
}
```

```rust
use langchain_rust::tools::SQLQuery;

let sql = SQLQuery::new("postgresql://user:pass@localhost/db".to_string());
let agent = ConversationalAgentBuilder::new()
    .tools(&[Arc::new(sql)])
    .build(llm)?;
```

--------------------------------

### GenerateResult to HashMap Conversion Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/09-types-schemas.md

Demonstrates how to convert a `GenerateResult` struct into a `HashMap` for easier data access. The resulting map includes keys for 'generation' and token usage statistics.

```rust
// To HashMap
let result = GenerateResult { /* ... */ };
let map = result.to_hashmap();
// Keys: "generation", "prompt_tokens", "completion_tokens", "total_tokens"
```

--------------------------------

### ConversationalChain Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/01-chains.md

Demonstrates how to initialize and use the ConversationalChain for a multi-turn conversation. It shows setting up the LLM and memory, building the chain, and making sequential calls where the conversation history is automatically preserved.

```rust
use langchain_rust::{
    chain::conversational::ConversationalChainBuilder,
    llm::openai::{OpenAI, OpenAIModel},
    memory::SimpleMemory,
    prompt_args,
};

let llm = OpenAI::default().with_model(OpenAIModel::Gpt4oMini.to_string());
let memory = SimpleMemory::new();

let chain = ConversationalChainBuilder::new()
    .llm(llm)
    .memory(memory)
    .build()?;

// First turn
let result1 = chain.invoke(prompt_args!("input" => "My name is Alice")).await?;
println!("{}", result1);

// Second turn - memory is automatically preserved
let result2 = chain.invoke(prompt_args!("input" => "What's my name?")).await?;
println!("{}", result2); // Will reference Alice from memory
```

--------------------------------

### Initialize and Use SerpAPI Search Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Demonstrates how to initialize the SerpApi tool with an API key and model, and then integrate it into a ConversationalAgent. Requires a SerpAPI key.

```rust
pub struct SerpApi {
    api_key: String,
    model: String,
}

impl SerpApi {
    pub fn new(api_key: String) -> Self;
    pub fn with_model<S: Into<String>>(mut self, model: S) -> Self;
    pub async fn simple_search(&self, query: &str) -> Result<String, Box<dyn Error>>;
}
```

```rust
use langchain_rust::tools::SerpApi;

let search = SerpApi::new("your-api-key".to_string())
    .with_model("google");

let agent = ConversationalAgentBuilder::new()
    .tools(&[Arc::new(search)])
    .build(llm)?;
```

--------------------------------

### Initialize QdrantVectorStore

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Creates a new QdrantVectorStore instance. Requires the Qdrant server URL, collection name, and the vector size (embedding dimension). Ensure Qdrant server is running.

```rust
use langchain_rust::vectorstore::QdrantVectorStore;

let vs = QdrantVectorStore::new(
    "http://localhost:6333".to_string(),
    "documents".to_string(),
    1536, // embedding dimension
).await?;
```

--------------------------------

### Search with SqliteVecVectorStore

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Performs a similarity search using the SqliteVecVectorStore. This example assumes the `similarity_search!` macro is available.

```rust
use langchain_rust::vectorstore::SqliteVecVectorStore;

let vs = SqliteVecVectorStore::new(
    "./vectors.db".to_string(),
    "embeddings".to_string(),
).await?;

let results = similarity_search!(vs, "query text", 10)?;
```

--------------------------------

### Initialize SQLQuery Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Creates a new SQLQuery tool instance. Requires a database connection string.

```rust
use langchain_rust::tools::SQLQuery;

let sql_tool = SQLQuery::new("postgresql://...".to_string());
```

--------------------------------

### Route Struct Definition

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Defines a static route with a name, example utterances, and a handler. Utterances are used for semantic matching.

```rust
pub struct Route {
    pub name: String,
    pub utterances: Vec<String>, // Examples of inputs for this route
    pub handler: String,          // Handler name
}

impl Route {
    pub fn new<S: Into<String>>(name: S, handler: S) -> Self;
    pub fn add_utterance<S: Into<String>>(mut self, utterance: S) -> Self;
}
```

--------------------------------

### Initialize and Use Wolfram Alpha Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Demonstrates initializing the WolframAlpha tool with an app ID and integrating it into a ConversationalAgent. Requires a WolframAlpha app ID.

```rust
pub struct WolframAlpha {
    app_id: String,
}

impl WolframAlpha {
    pub fn new(app_id: String) -> Self;
}
```

```rust
use langchain_rust::tools::WolframAlpha;

let wolfram = WolframAlpha::new("your-app-id".to_string());
let agent = ConversationalAgentBuilder::new()
    .tools(&[Arc::new(wolfram)])
    .build(llm)?;
```

--------------------------------

### Initialize Text to Speech Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Shows how to initialize the Text2Speech tool with specific voice and model configurations. Available voices include alloy, echo, fable, onyx, nova, shimmer.

```rust
pub struct Text2Speech {
    voice: String,
    model: String,
}

impl Text2Speech {
    pub fn new() -> Self;
    pub fn with_voice<S: Into<String>>(mut self, voice: S) -> Self;
    pub fn with_model<S: Into<String>>(mut self, model: S) -> Self;
}
```

```rust
use langchain_rust::tools::text2speech::Text2Speech;

let tts = Text2Speech::new()
    .with_voice("nova")
    .with_model("tts-1");
```

--------------------------------

### Preparing Documents for Vector Store

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/04-vectorstores.md

Shows how to create a vector of Document objects, each with basic content. This is the initial step before adding them to a vector store for indexing and retrieval.

```rust
let documents = vec![
    Document::new("First document"),
    Document::new("Second document"),
    Document::new("Third document"),
];
```

--------------------------------

### Initialize WolframAlpha Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Creates a new WolframAlpha tool instance. Requires an application ID for authentication.

```rust
use langchain_rust::tools::WolframAlpha;

let wolfram = WolframAlpha::new("app-id".to_string());
```

--------------------------------

### Add langchain-rust with Sqlite-vec Feature

Source: https://github.com/abraxas-365/langchain-rust/blob/main/README.md

Install `langchain-rust` with the `sqlite-vec` feature enabled. Ensure you have downloaded the necessary sqlite_vec libraries separately.

```bash
cargo add langchain-rust --features sqlite-vec
```

--------------------------------

### Add langchain-rust with Sqlite-vss Feature

Source: https://github.com/abraxas-365/langchain-rust/blob/main/README.md

Install `langchain-rust` with the `sqlite-vss` feature enabled. Ensure you have downloaded the necessary sqlite_vss libraries separately.

```bash
cargo add langchain-rust --features sqlite-vss
```

--------------------------------

### FastEmbedModel Enum Definition

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Defines the available FastEmbed models with their characteristics. Use the `ToString` implementation to get the model name as a string.

```rust
pub enum FastEmbedModel {
    BGSmallENV15,          // Multilingual, 384 dimensions
    BGSMALLENCN15,         // Chinese/English, 512 dimensions
    BGBaseENV15,           // English, 768 dimensions
    BGLargeENV15,          // English, 1024 dimensions
}

impl ToString for FastEmbedModel {
    fn to_string(&self) -> String { /* ... */ }
}
```

--------------------------------

### Document Q&A with Vector Store

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/00-index.md

Demonstrates loading documents, creating a vector store, and setting up a Q&A chain for querying document content. Requires a document loader and a vector store implementation.

```rust
let loader = PdfExtractLoader::from_path("doc.pdf")?;
let docs = loader.load().await?
    .collect::<Vec<_>>()
    .await;

let vs = /* create vector store */;
let ids = vs.add_documents(&docs, &options).await?;

let retriever = Retriever::new(vs, 5);
let chain = QAChainBuilder::new()
    .retriever(retriever)
    .llm(llm)
    .build()?;

let answer = chain.invoke(prompt_args! {
    "query" => "What does the document say about...?"
}).await?;
```

--------------------------------

### EmbedderError Handling Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Shows how to handle potential errors when calling embed_documents, specifically catching API errors and other general embedding errors.

```rust
match embedder.embed_documents(&docs).await {
    Ok(embeddings) => {
        // Process embeddings
    }
    Err(EmbedderError::APIError(msg)) => {
        eprintln!("API Error: {}", msg);
    }
    Err(e) => {
        eprintln!("Embedding Error: {:?}", e);
    }
}
```

--------------------------------

### Initialize SerpApi Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Creates a new SerpApi tool instance. Requires an API key and allows specifying a search model.

```rust
use langchain_rust::tools::SerpApi;

let search = SerpApi::new("your-api-key".to_string())
    .with_model("google");
```

--------------------------------

### Embedder Trait Usage Example

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/03-embeddings.md

Demonstrates how to use the `embed_documents` and `embed_query` methods of the `Embedder` trait. Ensure an `Embedder` implementation is available and awaited.

```rust
use langchain_rust::embedding::Embedder;

let documents = vec![
    "The quick brown fox".to_string(),
    "A lazy dog sleeps".to_string(),
];

// Assuming 'embedder' is an instance of a type implementing the Embedder trait
// let embeddings = embedder.embed_documents(&documents).await?;
// println!("Got {} embeddings", embeddings.len());

// let query_embedding = embedder.embed_query("fast animal").await?;
// println!("Query vector length: {}", query_embedding.len());
```

--------------------------------

### Initialize and Use DuckDuckGo Search Tool

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/10-tools-semantic-router.md

Shows how to initialize the DuckDuckGoSearch tool and add it to a ConversationalAgent. No API key is required, but rate limits apply.

```rust
pub struct DuckDuckGoSearch;

impl DuckDuckGoSearch {
    pub fn new() -> Self;
}
```

```rust
use langchain_rust::tools::DuckDuckGoSearch;

let search = DuckDuckGoSearch::new();
let agent = ConversationalAgentBuilder::new()
    .tools(&[Arc::new(search)])
    .build(llm)?;
```

--------------------------------

### Configure AgentExecutor for Error Handling

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/05-agents.md

Example showing how to configure AgentExecutor to stop execution immediately upon encountering a tool error by setting `break_if_error` to true.

```rust
let executor = AgentExecutor::from_agent(agent)
    .with_break_if_error(true); // Stop on first tool error

match executor.invoke(inputs).await {
    Ok(result) => println!("Success: {}", result),
    Err(e) => eprintln!("Agent error: {:?}", e),
}
```

--------------------------------

### Build and Invoke LLMChain

Source: https://github.com/abraxas-365/langchain-rust/blob/main/_autodocs/00-index.md

Shows how to construct an LLMChain using a prompt and an LLM, then invoke it with specific arguments. Ensure the prompt and LLM are properly defined.

```rust
let chain = LLMChainBuilder::new()
    .prompt(my_prompt)
    .llm(llm)
    .build()?;

let output = chain.invoke(prompt_args! {
    "input" => "..."
}).await?;
```