pull out LLM example, push down docs to main level

README.md

@@ -8,7 +8,7 @@ The main Mastra features are:
 
 | Features                                                                           | Description                                                                                                                                                                                                                                                                              |
 | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [LLM Models](https://mastra.ai/docs/guide/how-to/00-llm-models)                    | Mastra supports a variety of LLM providers, including OpenAI, Anthropic, Google Gemini. You can choose the specific model and provider, choose system and user prompts, and decide whether to stream the response.                                                                       |
+| [LLM Models](https://mastra.ai/docs/guide/llm-models/00-overview)                    | Mastra supports a variety of LLM providers, including OpenAI, Anthropic, Google Gemini. You can choose the specific model and provider, choose system and user prompts, and decide whether to stream the response.                                                                       |
 | [Agents](https://mastra.ai/docs/guide/how-to/01-creating-agents)                   | Agents are systems where the language model chooses a sequence of actions. In Mastra, agents provide LLM models with tools, workflows, and synced data. Agents can call your own functions or APIs of third-party integrations and access knowledge bases you build.                     |
 | [Tools](https://mastra.ai/docs/guide/how-to/02-adding-tools)                       | Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation. Each tool has a schema that defines its inputs, an executor function that implements its logic, and access to configured integrations.                 |
 | [Workflows](https://mastra.ai/docs/guide/how-to/03-building-workflows)             | Workflows are durable graph-based state machines. They have loops, branching, wait for human input, embed other workflows, do error handling, retries, parsing and so on. They can be built in code or with a visual editor. Each step in a workflow has built-in OpenTelemetry tracing. |

docs/src/pages/guide/how-to/04-knowledge-sources.mdx → docs/src/pages/guide/04-knowledge-sources.mdx

@@ -1,6 +1,5 @@
 ## Building a Knowledge Base
 
-
 RAG (Retrieval-Augmented Generation) enriches LLM outputs by retrieving relevant context from your own data. It typically involves:
 
 1. **Document Ingestion & Processing**: Break large documents into smaller chunks, extract metadata, and optionally enhance content with summaries, keywords, and Q&A hints.

docs/src/pages/guide/_meta.js

@@ -4,10 +4,18 @@ const meta = {
     title: "Getting Started",
     collapsed: false,
   },
-  "how-to": {
-    title: "How to",
+  "llm-models": {
+    title: "LLM Models",
     collapsed: false,
   },
+  "01-creating-agents": "Creating Agents",
+  "02-adding-tools": "Adding Tools",
+  "03-building-workflows": "Building Workflows",
+  "04-knowledge-sources": "Knowledge Sources",
+  "05-logging-and-telemetry": "Logging and Telemetry",
+  "06-adding-integrations": "Adding Integrations",
+  "07-deployment": "Deployment",
+  "08-running-evals": "Running Evals",
   reference: "Reference",
 };
 

docs/src/pages/guide/index.mdx

@@ -6,10 +6,10 @@ The main Mastra features are:
 
 | Features                                                       | Description                                                                                                                                                     |
 | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [LLM Models](../guide/how-to/00-llm-models.mdx)                | Mastra supports a variety of LLM providers, including OpenAI, Anthropic, Google Gemini.                                                                         |
-| [Agents](../guide/how-to/01-creating-agents)                   | Agents are systems where the language model chooses a sequence of actions.                                                                                      |
-| [Tools](../guide/how-to/02-adding-tools)                       | Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation.                               |
-| [Workflows](../guide/how-to/03-building-workflows)             | Workflows are durable graph-based state machines with built-in tracing. They can execute complex sequences of LLM operations.                                   |
-| [RAG](../guide/how-to/04-knowledge-sources)                    | Retrieval-augemented generation (RAG) lets you construct a knowledge base for your agents.                                                                      |
-| [Integrations & Syncs](../guide/how-to/06-adding-integrations) | In Mastra, syncs are async functions that can be deployed as background tasks. Integrations are auto-generated, type-safe API clients for third-party services. |
-| [Evals](../guide/how-to/08-running-evals)                      | Evals are automated tests that evaluate LLM outputs using model-graded, rule-based, and statistical methods.                                                    |
+| [LLM Models](../guide/llm-models/00-overview.mdx)                | Mastra supports a variety of LLM providers, including OpenAI, Anthropic, Google Gemini.                                                                         |
+| [Agents](../guide/01-creating-agents)                   | Agents are systems where the language model chooses a sequence of actions.                                                                                      |
+| [Tools](../guide/02-adding-tools)                       | Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation.                               |
+| [Workflows](../guide/03-building-workflows)             | Workflows are durable graph-based state machines with built-in tracing. They can execute complex sequences of LLM operations.                                   |
+| [RAG](../guide/04-knowledge-sources)                    | Retrieval-augemented generation (RAG) lets you construct a knowledge base for your agents.                                                                      |
+| [Integrations & Syncs](../guide/06-adding-integrations) | In Mastra, syncs are async functions that can be deployed as background tasks. Integrations are auto-generated, type-safe API clients for third-party services. |
+| [Evals](../guide/08-running-evals)                      | Evals are automated tests that evaluate LLM outputs using model-graded, rule-based, and statistical methods.                                                    |

docs/src/pages/guide/llm-models/00-overview.mdx

@@ -0,0 +1,164 @@
+# LLM Class Overview
+
+Mastra provides direct support for Large Language Models (LLMs) through the `LLM` class. The `LLM` class allows you to interact with various language models seamlessly, enabling you to generate text, handle conversations, and more. This guide covers:
+
+- How to initialize the LLM class.
+- Supported models and providers.
+- Using the `generate` function.
+- Message formats in `generate`.
+- Output formats in `generate`.
+
+---
+
+## Initializing the LLM Class
+
+To start using the `LLM` class, you need to initialize it with the desired model configuration. Here's how you can do it:
+
+```typescript
+import { Mastra } from '@mastra/core';
+
+const mastra = new Mastra();
+
+const llm = mastra.LLM({
+  provider: 'OPEN_AI',
+  name: 'gpt-4o',
+});
+```
+
+This initialization allows telemetry to pass through to the LLM, providing insights into model usage and performance.
+
+**Note:** You can find more details about the model configuration options in the [ModelConfig class reference](../reference/llm/model-config.mdx).
+
+---
+
+## Supported Models and Providers
+
+Mastra supports major LLM providers out of the box, plus additional providers through AI SDK integrations. Custom providers can also be added via the Portkey service.
+
+### Most Popular Providers and Models
+
+| Provider      | Supported Models                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **OpenAI**        | `gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo`, `gpt-4o`, `gpt-4o-mini`                                                                                                         |
+| **Anthropic**     | `claude-3-5-sonnet-20241022`, `claude-3-5-sonnet-20240620`, `claude-3-5-haiku-20241022`, `claude-3-opus-20240229`, `claude-3-sonnet-20240229`, `claude-3-haiku-20240307` |
+| **Google Gemini** | `gemini-1.5-pro-latest`, `gemini-1.5-pro`, `gemini-1.5-flash-latest`, `gemini-1.5-flash`                                                                                 |
+
+A full list of supported models can be found [here](../reference/llm/providers-and-models.mdx).
+
+---
+
+## The `generate` Function
+
+The main function you'll use with the `LLM` class is `generate`. It allows you to send messages to the language model and receive responses. The `generate` function takes:
+
+- **messages**: The first parameter, which can be a string, an array of strings, or an array of message objects.
+- **options**: The second parameter, which includes additional configurations like streaming, schemas for structured output, etc.
+
+This design covers all potential use cases and is extensible to multi-modal interactions in the future.
+
+---
+
+## Message Formats in `generate`
+
+The `generate` function supports three types of message formats:
+
+### 1. Simple String
+
+You can pass a single string as the message:
+
+```typescript
+const response = await llm.generate('Tell me a joke.');
+```
+
+### 2. Array of Strings
+
+You can provide an array of strings, which will be converted into user messages:
+
+```typescript
+const response = await llm.generate([
+  'Hello!',
+  'Can you explain quantum mechanics?',
+]);
+```
+
+### 3. Detailed Message Objects
+
+For finer control, you can pass an array of message objects, specifying the role and content:
+
+```typescript
+const response = await llm.generate([
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'What is the meaning of life?' },
+]);
+```
+
+---
+
+## Output Formats in `generate`
+
+The `generate` function supports four types of output formats:
+
+### 1. Simple Text Generation
+
+Receive a basic text response from the model:
+
+```typescript
+const response = await llm.generate('What is AI?');
+
+console.log(response.text);
+```
+
+### 2. Structured Output
+
+Request a structured response by providing a schema. This is useful when you need the output in a specific format:
+
+```typescript
+import { z } from 'zod';
+
+const mySchema = z.object({
+  definition: z.string(),
+  examples: z.array(z.string()),
+});
+
+const response = await llm.generate('Define machine learning and give examples.', {
+  schema: mySchema,
+});
+
+console.log(response.object);
+```
+
+### 3. Streaming Text
+
+Stream the response in real-time, which is useful for handling longer outputs or providing immediate feedback to users:
+
+```typescript
+const stream = await llm.generate('Tell me a story about a brave knight.', {
+  stream: true,
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### 4. Streaming Structured Output
+
+Stream a structured response using a schema:
+
+```typescript
+const stream = await llm.generate('Provide live weather data.', {
+  schema: mySchema,
+  stream: true,
+});
+
+for await (const chunk of stream.textStream) {
+  console.log(chunk);
+}
+```
+
+---
+
+## Additional Notes
+
+- **Telemetry**: Initializing the `LLM` class through Mastra allows telemetry data to pass through, enabling better monitoring and debugging.
+- **Extensibility**: The design of the `generate` function and message formats makes it future-proof and extensible for multi-modal interactions.