diff --git a/docs/README.md b/docs/README.md
index 1847e49d8..01c6bda59 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,6 +13,19 @@ npm run serve
```
You can open up the docs in your browser at http://localhost:3000
+## File Import System
+
+This documentation uses a custom component to import files directly from the repository, eliminating copy-paste maintenance:
+
+```jsx
+import CodeFromFile from '@site/src/components/CodeFromFile';
+
+
+
+```
+
+Files are automatically synced from the repo root when building. See the `CodeFromFile` component for syntax highlighting, line ranges, and multi-language support.
+
## Content
Try out Llama Stack's capabilities through our detailed Jupyter notebooks:
diff --git a/docs/docs/getting_started/demo_script.py b/docs/docs/getting_started/demo_script.py
index 2ea67739f..3971ae46e 100644
--- a/docs/docs/getting_started/demo_script.py
+++ b/docs/docs/getting_started/demo_script.py
@@ -4,65 +4,24 @@
# This source code is licensed under the terms described in the LICENSE file in
# the root directory of this source tree.
-from llama_stack_client import Agent, AgentEventLogger, RAGDocument, LlamaStackClient
-vector_db_id = "my_demo_vector_db"
-client = LlamaStackClient(base_url="http://localhost:8321")
+import io, requests
+from openai import OpenAI
-models = client.models.list()
+url="https://www.paulgraham.com/greatwork.html"
+client = OpenAI(base_url="http://localhost:8321/v1/", api_key="none")
-# Select the first LLM and first embedding models
-model_id = next(m for m in models if m.model_type == "llm").identifier
-embedding_model_id = (
- em := next(m for m in models if m.model_type == "embedding")
-).identifier
-embedding_dimension = em.metadata["embedding_dimension"]
+vs = client.vector_stores.create()
+response = requests.get(url)
+pseudo_file = io.BytesIO(str(response.content).encode('utf-8'))
+uploaded_file = client.files.create(file=(url, pseudo_file, "text/html"), purpose="assistants")
+client.vector_stores.files.create(vector_store_id=vs.id, file_id=uploaded_file.id)
-vector_db = client.vector_dbs.register(
- vector_db_id=vector_db_id,
- embedding_model=embedding_model_id,
- embedding_dimension=embedding_dimension,
- provider_id="faiss",
-)
-vector_db_id = vector_db.identifier
-source = "https://www.paulgraham.com/greatwork.html"
-print("rag_tool> Ingesting document:", source)
-document = RAGDocument(
- document_id="document_1",
- content=source,
- mime_type="text/html",
- metadata={},
-)
-client.tool_runtime.rag_tool.insert(
- documents=[document],
- vector_db_id=vector_db_id,
- chunk_size_in_tokens=100,
-)
-agent = Agent(
- client,
- model=model_id,
- instructions="You are a helpful assistant",
- tools=[
- {
- "name": "builtin::rag/knowledge_search",
- "args": {"vector_db_ids": [vector_db_id]},
- }
- ],
+resp = client.responses.create(
+ model="gpt-4o",
+ input="How do you do great work? Use the existing knowledge_search tool.",
+ tools=[{"type": "file_search", "vector_store_ids": [vs.id]}],
+ include=["file_search_call.results"],
)
-prompt = "How do you do great work?"
-print("prompt>", prompt)
-
-use_stream = True
-response = agent.create_turn(
- messages=[{"role": "user", "content": prompt}],
- session_id=agent.create_session("rag_session"),
- stream=use_stream,
-)
-
-# Only call `AgentEventLogger().log(response)` for streaming responses.
-if use_stream:
- for log in AgentEventLogger().log(response):
- log.print()
-else:
- print(response)
+print(resp)
diff --git a/docs/docs/getting_started/quickstart.mdx b/docs/docs/getting_started/quickstart.mdx
index b885f3c66..c213cd04b 100644
--- a/docs/docs/getting_started/quickstart.mdx
+++ b/docs/docs/getting_started/quickstart.mdx
@@ -32,76 +32,9 @@ OLLAMA_URL=http://localhost:11434 \
#### Step 3: Run the demo
Now open up a new terminal and copy the following script into a file named `demo_script.py`.
-```python title="demo_script.py"
-# Copyright (c) Meta Platforms, Inc. and affiliates.
-# All rights reserved.
-#
-# This source code is licensed under the terms described in the LICENSE file in
-# the root directory of this source tree.
+import CodeFromFile from '@site/src/components/CodeFromFile';
-from llama_stack_client import Agent, AgentEventLogger, RAGDocument, LlamaStackClient
-
-vector_db_id = "my_demo_vector_db"
-client = LlamaStackClient(base_url="http://localhost:8321")
-
-models = client.models.list()
-
-# Select the first LLM and first embedding models
-model_id = next(m for m in models if m.model_type == "llm").identifier
-embedding_model_id = (
- em := next(m for m in models if m.model_type == "embedding")
-).identifier
-embedding_dimension = em.metadata["embedding_dimension"]
-
-vector_db = client.vector_dbs.register(
- vector_db_id=vector_db_id,
- embedding_model=embedding_model_id,
- embedding_dimension=embedding_dimension,
- provider_id="faiss",
-)
-vector_db_id = vector_db.identifier
-source = "https://www.paulgraham.com/greatwork.html"
-print("rag_tool> Ingesting document:", source)
-document = RAGDocument(
- document_id="document_1",
- content=source,
- mime_type="text/html",
- metadata={},
-)
-client.tool_runtime.rag_tool.insert(
- documents=[document],
- vector_db_id=vector_db_id,
- chunk_size_in_tokens=100,
-)
-agent = Agent(
- client,
- model=model_id,
- instructions="You are a helpful assistant",
- tools=[
- {
- "name": "builtin::rag/knowledge_search",
- "args": {"vector_db_ids": [vector_db_id]},
- }
- ],
-)
-
-prompt = "How do you do great work?"
-print("prompt>", prompt)
-
-use_stream = True
-response = agent.create_turn(
- messages=[{"role": "user", "content": prompt}],
- session_id=agent.create_session("rag_session"),
- stream=use_stream,
-)
-
-# Only call `AgentEventLogger().log(response)` for streaming responses.
-if use_stream:
- for log in AgentEventLogger().log(response):
- log.print()
-else:
- print(response)
-```
+
We will use `uv` to run the script
```
uv run --with llama-stack-client,fire,requests demo_script.py
diff --git a/docs/package.json b/docs/package.json
index 6bbc48eb0..93b0f8280 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -4,8 +4,8 @@
"private": true,
"scripts": {
"docusaurus": "docusaurus",
- "start": "docusaurus start",
- "build": "docusaurus build",
+ "start": "npm run sync-files && docusaurus start",
+ "build": "npm run sync-files && docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
@@ -15,7 +15,8 @@
"gen-api-docs": "docusaurus gen-api-docs",
"clean-api-docs": "docusaurus clean-api-docs",
"gen-api-docs:version": "docusaurus gen-api-docs:version",
- "clean-api-docs:version": "docusaurus clean-api-docs:version"
+ "clean-api-docs:version": "docusaurus clean-api-docs:version",
+ "sync-files": "node scripts/sync-files.js"
},
"dependencies": {
"@docusaurus/core": "3.8.1",
diff --git a/docs/scripts/sync-files.js b/docs/scripts/sync-files.js
new file mode 100755
index 000000000..6b1fc86ca
--- /dev/null
+++ b/docs/scripts/sync-files.js
@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Repository root is always one level up from docs
+const repoRoot = path.join(__dirname, '..', '..');
+
+// Get all requested files from the usage tracking file
+function getRequestedFiles() {
+ const usageFile = path.join(__dirname, '..', 'static', 'imported-files', 'usage.json');
+ if (!fs.existsSync(usageFile)) {
+ return [];
+ }
+
+ try {
+ const usage = JSON.parse(fs.readFileSync(usageFile, 'utf8'));
+ return usage.files || [];
+ } catch (error) {
+ console.warn('Could not read usage file:', error.message);
+ return [];
+ }
+}
+
+// Track file usage
+function trackFileUsage(filePath) {
+ const usageFile = path.join(__dirname, '..', 'static', 'imported-files', 'usage.json');
+ const usageDir = path.dirname(usageFile);
+
+ // Ensure directory exists
+ if (!fs.existsSync(usageDir)) {
+ fs.mkdirSync(usageDir, { recursive: true });
+ }
+
+ let usage = { files: [] };
+ if (fs.existsSync(usageFile)) {
+ try {
+ usage = JSON.parse(fs.readFileSync(usageFile, 'utf8'));
+ } catch (error) {
+ console.warn('Could not read existing usage file, creating new one');
+ }
+ }
+
+ if (!usage.files.includes(filePath)) {
+ usage.files.push(filePath);
+ fs.writeFileSync(usageFile, JSON.stringify(usage, null, 2));
+ }
+}
+
+// Sync a file from repo root to static directory
+function syncFile(filePath) {
+ const sourcePath = path.join(repoRoot, filePath);
+ const destPath = path.join(__dirname, '..', 'static', 'imported-files', filePath);
+ const destDir = path.dirname(destPath);
+
+ // Ensure destination directory exists
+ if (!fs.existsSync(destDir)) {
+ fs.mkdirSync(destDir, { recursive: true });
+ }
+
+ try {
+ if (fs.existsSync(sourcePath)) {
+ const content = fs.readFileSync(sourcePath, 'utf8');
+ fs.writeFileSync(destPath, content);
+ console.log(`ā
Synced ${filePath}`);
+ trackFileUsage(filePath);
+ return true;
+ } else {
+ console.warn(`ā ļø Source file not found: ${sourcePath}`);
+ return false;
+ }
+ } catch (error) {
+ console.error(`ā Error syncing ${filePath}:`, error.message);
+ return false;
+ }
+}
+
+// Main execution
+console.log(`š Repository root: ${path.resolve(repoRoot)}`);
+
+// Get files that are being requested by the documentation
+const requestedFiles = getRequestedFiles();
+console.log(`š Syncing ${requestedFiles.length} requested files...`);
+
+if (requestedFiles.length === 0) {
+ console.log('ā¹ļø No files requested yet. Files will be synced when first referenced in documentation.');
+} else {
+ requestedFiles.forEach(filePath => {
+ syncFile(filePath);
+ });
+}
+
+console.log('ā
File sync complete!');
diff --git a/docs/src/components/CodeFromFile.jsx b/docs/src/components/CodeFromFile.jsx
new file mode 100644
index 000000000..e2ef1d7cf
--- /dev/null
+++ b/docs/src/components/CodeFromFile.jsx
@@ -0,0 +1,119 @@
+import React, { useState, useEffect } from 'react';
+import CodeBlock from '@theme/CodeBlock';
+
+export default function CodeFromFile({
+ src,
+ language = 'python',
+ title,
+ startLine,
+ endLine,
+ highlightLines
+}) {
+ const [content, setContent] = useState('');
+ const [error, setError] = useState(null);
+
+ useEffect(() => {
+ async function loadFile() {
+ try {
+ // Register this file for syncing (build-time only)
+ if (typeof window === 'undefined') {
+ // This runs during build - register the file
+ const fs = require('fs');
+ const path = require('path');
+
+ const usageFile = path.join(process.cwd(), 'static', 'imported-files', 'usage.json');
+ const usageDir = path.dirname(usageFile);
+
+ if (!fs.existsSync(usageDir)) {
+ fs.mkdirSync(usageDir, { recursive: true });
+ }
+
+ let usage = { files: [] };
+ if (fs.existsSync(usageFile)) {
+ try {
+ usage = JSON.parse(fs.readFileSync(usageFile, 'utf8'));
+ } catch (error) {
+ console.warn('Could not read existing usage file');
+ }
+ }
+
+ if (!usage.files.includes(src)) {
+ usage.files.push(src);
+ fs.writeFileSync(usageFile, JSON.stringify(usage, null, 2));
+ }
+ }
+
+ // Load file from static/imported-files directory
+ const response = await fetch(`/imported-files/${src}`);
+ if (!response.ok) {
+ throw new Error(`Failed to fetch: ${response.status}`);
+ }
+ let text = await response.text();
+
+ // Handle line range if specified
+ if (startLine || endLine) {
+ const lines = text.split('\n');
+ const start = startLine ? Math.max(0, startLine - 1) : 0;
+ const end = endLine ? Math.min(lines.length, endLine) : lines.length;
+ text = lines.slice(start, end).join('\n');
+ }
+
+ setContent(text);
+ } catch (err) {
+ console.error('Failed to load file:', err);
+ setError(`Failed to load ${src}: ${err.message}`);
+ }
+ }
+
+ loadFile();
+ }, [src, startLine, endLine]);
+
+ if (error) {
+ return
+ Error: {error}
+
;
+ }
+
+ if (!content) {
+ return Loading {src}...
;
+ }
+
+ // Auto-detect language from file extension if not provided
+ const detectedLanguage = language || getLanguageFromExtension(src);
+
+ return (
+
+ {content}
+
+ );
+}
+
+function getLanguageFromExtension(filename) {
+ const ext = filename.split('.').pop();
+ const languageMap = {
+ 'py': 'python',
+ 'js': 'javascript',
+ 'jsx': 'jsx',
+ 'ts': 'typescript',
+ 'tsx': 'tsx',
+ 'md': 'markdown',
+ 'sh': 'bash',
+ 'yaml': 'yaml',
+ 'yml': 'yaml',
+ 'json': 'json',
+ 'css': 'css',
+ 'html': 'html',
+ 'cpp': 'cpp',
+ 'c': 'c',
+ 'java': 'java',
+ 'go': 'go',
+ 'rs': 'rust',
+ 'php': 'php',
+ 'rb': 'ruby',
+ };
+ return languageMap[ext] || 'text';
+}
diff --git a/docs/static/imported-files/README.md b/docs/static/imported-files/README.md
new file mode 100644
index 000000000..75e9989d7
--- /dev/null
+++ b/docs/static/imported-files/README.md
@@ -0,0 +1,207 @@
+# Llama Stack
+
+[](https://pypi.org/project/llama_stack/)
+[](https://pypi.org/project/llama-stack/)
+[](https://github.com/meta-llama/llama-stack/blob/main/LICENSE)
+[](https://discord.gg/llama-stack)
+[](https://github.com/meta-llama/llama-stack/actions/workflows/unit-tests.yml?query=branch%3Amain)
+[](https://github.com/meta-llama/llama-stack/actions/workflows/integration-tests.yml?query=branch%3Amain)
+
+[**Quick Start**](https://llamastack.github.io/docs/getting_started/quickstart) | [**Documentation**](https://llamastack.github.io/docs) | [**Colab Notebook**](./docs/getting_started.ipynb) | [**Discord**](https://discord.gg/llama-stack)
+
+
+### āØš Llama 4 Support šāØ
+We released [Version 0.2.0](https://github.com/meta-llama/llama-stack/releases/tag/v0.2.0) with support for the Llama 4 herd of models released by Meta.
+
+
+
+š Click here to see how to run Llama 4 models on Llama Stack
+
+\
+*Note you need 8xH100 GPU-host to run these models*
+
+```bash
+pip install -U llama_stack
+
+MODEL="Llama-4-Scout-17B-16E-Instruct"
+# get meta url from llama.com
+huggingface-cli download meta-llama/$MODEL --local-dir ~/.llama/$MODEL
+
+# start a llama stack server
+INFERENCE_MODEL=meta-llama/$MODEL llama stack build --run --template meta-reference-gpu
+
+# install client to interact with the server
+pip install llama-stack-client
+```
+### CLI
+```bash
+# Run a chat completion
+MODEL="Llama-4-Scout-17B-16E-Instruct"
+
+llama-stack-client --endpoint http://localhost:8321 \
+inference chat-completion \
+--model-id meta-llama/$MODEL \
+--message "write a haiku for meta's llama 4 models"
+
+OpenAIChatCompletion(
+ ...
+ choices=[
+ OpenAIChatCompletionChoice(
+ finish_reason='stop',
+ index=0,
+ message=OpenAIChatCompletionChoiceMessageOpenAIAssistantMessageParam(
+ role='assistant',
+ content='...**Silent minds awaken,** \n**Whispers of billions of words,** \n**Reasoning breaks the night.** \n\nā \n*This haiku blends the essence of LLaMA 4\'s capabilities with nature-inspired metaphor, evoking its vast training data and transformative potential.*',
+ ...
+ ),
+ ...
+ )
+ ],
+ ...
+)
+```
+### Python SDK
+```python
+from llama_stack_client import LlamaStackClient
+
+client = LlamaStackClient(base_url=f"http://localhost:8321")
+
+model_id = "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+prompt = "Write a haiku about coding"
+
+print(f"User> {prompt}")
+response = client.chat.completions.create(
+ model=model_id,
+ messages=[
+ {"role": "system", "content": "You are a helpful assistant."},
+ {"role": "user", "content": prompt},
+ ],
+)
+print(f"Assistant> {response.choices[0].message.content}")
+```
+As more providers start supporting Llama 4, you can use them in Llama Stack as well. We are adding to the list. Stay tuned!
+
+
+
+
+### š One-Line Installer š
+
+To try Llama Stack locally, run:
+
+```bash
+curl -LsSf https://github.com/meta-llama/llama-stack/raw/main/scripts/install.sh | bash
+```
+
+### Overview
+
+Llama Stack standardizes the core building blocks that simplify AI application development. It codifies best practices across the Llama ecosystem. More specifically, it provides
+
+- **Unified API layer** for Inference, RAG, Agents, Tools, Safety, Evals, and Telemetry.
+- **Plugin architecture** to support the rich ecosystem of different API implementations in various environments, including local development, on-premises, cloud, and mobile.
+- **Prepackaged verified distributions** which offer a one-stop solution for developers to get started quickly and reliably in any environment.
+- **Multiple developer interfaces** like CLI and SDKs for Python, Typescript, iOS, and Android.
+- **Standalone applications** as examples for how to build production-grade AI applications with Llama Stack.
+
+
+
+
+
diff --git a/docs/static/imported-files/usage.json b/docs/static/imported-files/usage.json
new file mode 100644
index 000000000..3692a65e5
--- /dev/null
+++ b/docs/static/imported-files/usage.json
@@ -0,0 +1,6 @@
+{
+ "files": [
+ "docs/getting_started/demo_script.py",
+ "README.md"
+ ]
+}