Docs: update index and getting started

docs/docs/getting-started/quickstart.mdx

@@ -4,78 +4,85 @@ description: "Start building awesome LLM pipelines in minutes"
 icon: "rocket"
 ---
 
-This guide will walk you through setting up DSRs in your Rust project and building your first LLM pipeline. You'll learn how to install the necessary dependencies, configure your language model provider, create a simple signature, and run your first prediction.
-
-The entire process takes about 10-15 minutes and requires only basic Rust knowledge. We'll start with installation, then move through configuration, and finally build a practical example that you can extend for your own use cases.
-
-<Steps>
-<Step title="Install DSRs">
-
-You can add DSRs to your project just like any other Rust crate, using either of these two methods:
-
-**Option 1: Add via Cargo.toml**
-```toml
-[dependencies]
-dsrs = { package = "dspy-rs", version = "0.0.2-beta" }
+We'll begin with a 2-minute quickstart to get you running immediately. Afterward, a more detailed, chapter-by-chapter guided tour will deconstruct the concepts, empowering you to build truly sophisticated AI pipelines.
+
+## Quickstart: Your First Prediction in 2 Minutes
+This section is designed for action. Follow these steps to get from a new project to a working LLM-powered program as fast as possible.
+**Prerequisites:**
+*   A working Rust toolchain.
+*   An [OpenAI API key](https://platform.openai.com/api-keys).
+### Step 1: Create a New Project
+```bash
+cargo new dsrs_quickstart
+cd dsrs_quickstart
 ```
-
-**Option 2: Add via cargo command**
+### Step 2: Add Dependencies
+We'll add `dspy-rs` (with the recommended `dsrs` alias) and a few essential support crates.
 ```bash
 cargo add dsrs --package dspy-rs
+cargo add tokio -F full
+cargo add anyhow
+cargo add secrecy
 ```
-
-This will create an alias `dsrs` for the `dspy-rs` crate which is the intended way to use it.
-
-<Note>
-The reason we wanna do aliasing is because `dsrs` was already a published crate so I couldn't get the name, but this is how we intend to use it.
-</Note>
-</Step>
-
-<Step title="Setting up your Language Model">
-
-Create a `.env` file in your project root to configure your language model provider:
-
-```bash
-mint dev
+### Step 3: Set Your API Key
+Create a `.env` file in the root of your `dsrs_quickstart` project and add your API key.
+```dotenv
+# .env
+OPENAI_API_KEY="sk-..."
 ```
-
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-</Step>
-
-<Step title="Define Task via Signatures">
-
-Create a `.env` file in your project root to configure your language model provider:
-
-```bash
-mint dev
+### Step 4: Write the Code
+Replace the contents of `src/main.rs` with the following complete example:
+```rust
+// src/main.rs
+use dsrs::prelude::*;
+use anyhow::Result;
+use secrecy::SecretString;
+// 1. Define a "Signature"
+// This is a typed contract for what the LLM should do.
+// The doc comment becomes the main instruction.
+#[Signature]
+/// Answer questions about geography.
+struct GeographyQA {
+    #[input]
+    question: String,
+    #[output]
+    answer: String,
+}
+#[tokio::main]
+async fn main() -> Result<()> {
+    // 2. Configure the Language Model (one-time setup)
+    let api_key = std::env::var("OPENAI_API_KEY")
+        .expect("OPENAI_API_KEY must be set in your .env file");
+    configure(
+        LM::builder()
+            .api_key(SecretString::from(api_key))
+            .build(),
+        ChatAdapter::default(),
+    );
+    // 3. Create a "Predictor" module for our signature
+    let qa_predictor = Predict::new(GeographyQA::new());
+    // 4. Prepare an "Example" with our input data
+    let user_question = example! {
+        "question": "input" => "What is the highest mountain in North America?",
+    };
+    // 5. Run the prediction
+    println!("Asking the LLM...");
+    let result = qa_predictor.forward(user_question).await?;
+    // 6. Use the strongly-typed "Prediction" output
+    println!("\nAnswer: {}", result.get("answer", None));
+    Ok(())
+}
 ```
-
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-</Step>
-
-<Step title="Setting Predictor for Signature Execution">
-
-Create a `.env` file in your project root to configure your language model provider:
-
+### Step 5: Run It!
+Execute the program from your terminal:
 ```bash
-mint dev
+# cargo run
 ```
-
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-</Step>
-
-<Step title="Building Modules for Complex Pipelines">
-
-Create a `.env` file in your project root to configure your language model provider:
-
-```bash
-mint dev
+You should see output similar to this:
 ```
+Asking the LLM...
+Answer: "The highest mountain in North America is Denali."
+```
+Congratulations! You've successfully executed your first `DSRs` pipeline. You defined a typed task, sent it to an LLM, and got a structured response back.
+To understand the magic behind each of these steps, continue to our Guided Tour.
 
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-</Step>
-</Steps>

docs/index.mdx

@@ -18,7 +18,25 @@ iconType: "light"
   }}
 />
 
-DSRs is a rewrite of the DSPy framework, built from the ground up in Rust for programming robust, LLM-powered applications. By leveraging Rust’s type system, memory safety, and concurrency, DSRs offers a more efficient and reliable foundation for language model workflows.
+Welcome to the official documentation for `DSRs` (DSPy Rust). This guide provides a comprehensive walkthrough of the framework, from first principles to advanced pipeline construction. It's written for developers who are familiar with modern software engineering practices and are looking to build robust, high-performance applications powered by Language Models.
+
+### For the DSPy Veteran
+
+You understand the power of separating logic from prompting and optimizing complex pipelines. `DSRs` offers the same conceptual elegance you love, but supercharged with Rust's compile-time guarantees. Imagine your DSPy modules, but with:
+-   **Static Typing:** Catch schema mismatches at compile time, not runtime.
+-   **Blazing Performance:** Leverage Rust's efficiency for low-latency inference and data processing.
+-   **Fearless Concurrency:** Build highly parallel pipelines with native `async/await`.
+-   **Reliability:** Eliminate entire classes of bugs related to data shape and null values.
+
+### For the Rust Artisan
+
+You build fast, reliable systems. `DSRs` provides a principled, idiomatic Rust framework for taming the non-deterministic nature of LLMs. Instead of ad-hoc string formatting and manual JSON parsing, you get:
+-   **Declarative Macros:** Define complex LLM interactions with the `#[Signature]` macro.
+-   **Type-Safe Schemas:** Automatically generate and enforce JSON schemas for structured outputs.
+-   **Composable Modules:** Build complex logic graphs using the `Module` trait, just as you would with other systems-level components.
+-   **Asynchronous Core:** Designed from the ground up for the `tokio` ecosystem.
+
+---
 
 - **Not just a port:** DSRs reimagines DSPy’s abstractions with Rust’s strengths in mind.
 - **Modern Rust API:** Take advantage of Rust’s ecosystem, async support, and strong typing.
@@ -27,7 +45,29 @@ DSRs is a rewrite of the DSPy framework, built from the ground up in Rust for pr
 
 > _Inspired by the original [DSPy](https://github.com/stanfordnlp/dspy) framework, DSRs brings LLM application development to the Rust community._
 
+---
+
+## Table of Contents
 
+1.  [**Getting Started: Your First LLM Call**](#1-getting-started-your-first-llm-call)
+    -   Installation & Setup
+    -   A Complete, Runnable Example
+2.  [**Core Concepts: The Building Blocks**](#2-core-concepts-the-building-blocks)
+    -   **Signatures:** The Typed API for LLMs
+    -   **Predictors:** The Inference Engine
+    -   **Language Models (LM):** Configuring the Backend
+    -   **Modules:** Composing Complex Workflows
+    -   **Data Flow:** `Example` and `Prediction`
+3.  [**Practical Guides & Advanced Usage**](#3-practical-guides--advanced-usage)
+    -   **Guide 1: Structured Data Extraction**
+    -   **Guide 2: Building a Multi-Step Pipeline (Module Composition)**
+    -   **Guide 3: Chain-of-Thought (CoT) Reasoning**
+4.  [**Testing and Development**](#4-testing-and-development)
+    -   Unit Testing with `DummyLM`
+    -   CI and Quality Gates
+5.  [**API Reference**](#5-api-reference)
+
+---
 ## Setting up
 
 Get your documentation site up and running in minutes.