stanfordnlp · chenmoneygithub · Dec 15, 2024 · Dec 15, 2024 · Dec 15, 2024 · Dec 17, 2024
diff --git a/.gitignore b/.gitignore
@@ -7,6 +7,7 @@
 /logs/
 /docs/downloads/
 /docs/experiments/
+/docs/docs/api/
 
 /examples/qa/hotpot/MIPRO_notebook_cache/
 /examples/nli/scone/MIPRO_notebook_cache/

diff --git a/docs/README.md b/docs/README.md
@@ -16,7 +16,13 @@ To build and test the documentation locally:
    pip install -r requirements.txt
    ```
 
-3. Run the build command:
+3. Generate the API docs and index them:
+   ```bash
+   python scripts/generate_api_docs.py
+   python scripts/generate_api_summary.py
+   ```
+
+4. Run the build command:
    ```bash
    mkdocs build
    ```

diff --git a/docs/docs/learn/evaluation/overview.md b/docs/docs/learn/evaluation/overview.md
@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# Evaluation in DSPy
+# Evaluate your DSPy program
 
 Once you have an initial system, it's time to **collect an initial development set** so you can refine it more systematically. Even 20 input examples of your task can be useful, though 200 goes a long way. Depending on your _metric_, you either just need inputs and no labels at all, or you need inputs and the _final_ outputs of your system. (You almost never need labels for the intermediate steps in your program in DSPy.) You can probably find datasets that are adjacent to your task on, say, HuggingFace datasets or in a naturally occuring source like StackExchange. If there's data whose licenses are permissive enough, we suggest you use them. Otherwise, you can label a few examples by hand or start deploying a demo of your system and collect initial data that way.
 

diff --git a/docs/docs/learn/index.md b/docs/docs/learn/index.md
@@ -4,12 +4,19 @@ sidebar_position: 1
 
 # Learning DSPy: An Overview
 
-DSPy exposes a very small API that you can learn quickly. However, building a new AI system is a more open-ended journey of iterative development, in which you compose the tools and design patterns of DSPy to optimize for _your_ objectives. The three stages of building AI systems in DSPy are:
+DSPy exposes a very small number of APIs that you can learn quickly. However, building a compound AI system is a open-ended journey of
+iterative development, in which you compose the tools and design patterns of DSPy to optimize for _your_ objectives. The three stages of
+building AI systems in DSPy are:
 
-1) **DSPy Programming.** This is about defining your task, its constraints, exploring a few examples, and using that to inform your initial pipeline design.
+1) **Building your DSPy program.** The first stage is defining your task, then choosing your language models, defining your signatures,
+   and building your DSPy modules and combine them into a DSPy program.
 
-2) **DSPy Evaluation.** Once your system starts working, this is the stage where you collect an initial development set, define your DSPy metric, and use these to iterate on your system more systematically.
+2) **Evaluating your DSPy program.** Once your system starts working, this is the stage where you evalute how your program performs in
+   your selected task. You need to collect a development/test dataset, and define your evaluation metric, the metric is an indicator
+   of your program's performance.
 
-3) **DSPy Optimization.** Once you have a way to evaluate your system, you use DSPy optimizers to tune the prompts or weights in your program.
+3) **Optimizing your DSPy program.** Once you have a way to evaluate your system, you can use DSPy optimizers to improve your program. DSPy
+   optimizers can tune both the prompts and weights in your program.
 
-We suggest learning and applying DSPy in this order. For example, it's unproductive to launch optimization runs using a poorly-design program or a bad metric.
+We suggest learning and applying DSPy in this order. For example, it's unproductive to launch optimization runs using a poorly-design program
+or a bad metric.
diff --git a/docs/docs/learn/optimization/overview.md b/docs/docs/learn/optimization/overview.md
@@ -3,7 +3,7 @@ sidebar_position: 1
 ---
 
 
-# Optimization in DSPy
+# Optimize your DSPy program
 
 Once you have a system and a way to evaluate it, you can use DSPy optimizers to tune the prompts or weights in your program. Now it's useful to expand your data collection effort into building a training set and a held-out test set, in addition to the development set you've been using for exploration. For the training set (and its subset, validation set), you can often get substantial value out of 30 examples, but aim for at least 300 examples. Some optimizers accept a `trainset` only. Others ask for a `trainset` and a `valset`. For prompt optimizers, we suggest starting with a 20% split for training and 80% for validation, which is often the _opposite_ of what one does for DNNs.
 

diff --git a/docs/docs/learn/programming/overview.md b/docs/docs/learn/programming/overview.md
@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# Programming in DSPy
+# Build your DSPy program
 
 DSPy is a bet on _writing code instead of strings_. In other words, building the right control flow is crucial. Start by **defining your task**. What are the inputs to your system and what should your system produce as output? Is it a chatbot over your data or perhaps a code assistant? Or maybe a system for translation, for highlighting snippets from search results, or for generating reports with citations?
 

diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css
@@ -1,14 +1,12 @@
 /* Custom styles for logo */
-.md-logo {
+.md-logo, .md-logo img {
     width: auto !important;
-    height: 1.5rem !important; /* Reduced from 1.8rem */
+    height: 1.5rem !important;
     padding: 0 !important;
     margin: 0 !important;
 }
 
 .md-logo img {
-    width: auto !important;
-    height: 1.5rem !important; /* Reduced from 1.8rem */
     object-fit: contain !important;
 }
 
@@ -47,13 +45,6 @@
     }
 }
 
-/* Fully responsive on smaller screens */
-/* @media (max-width: 6px) {
-    .md-content {
-        max-width: 98%;
-    }
-} */
-
 
 /* Justified text for main content */
 .md-content__inner p {
@@ -105,3 +96,136 @@ body[data-md-color-scheme="slate"] .jp-Cell-outputWrapper .jp-OutputArea-output
 .md-sidebar {
     width: 235px;
 }
+
+/* Adjust search bar position */
+.md-search {
+    margin-left: auto;
+    padding-right: 0;
+}
+
+/* If you need to adjust the width of the search bar */
+.md-search__inner {
+    width: 13rem;
+}
+
+/* Adjust repository button position and alignment */
+.md-header__source {
+    margin-left: 1rem;
+    margin-right: 0;
+    text-align: right;  /* Keep right alignment for container */
+    width: auto;  /* Allow container to shrink to content */
+}
+
+.md-header__source .md-source {
+    justify-content: flex-start;  /* Change to flex-start to align text to left */
+    width: auto;  /* Allow element to shrink to content */
+    min-width: 0;  /* Remove minimum width constraint */
+}
+
+.md-header__source .md-source__icon {
+    order: 2;  /* Keep icon on the right */
+    margin-left: 0.5rem;
+    margin-right: 0;
+}
+
+.md-header__source .md-source__repository {
+    order: 1;  /* Keep text on the left */
+    text-align: left;  /* Ensure text is left-aligned */
+    width: auto;  /* Allow text container to shrink */
+}
+
+h2.doc-heading {
+    font-size: 1rem;
+    font-weight: 700;
+}
+
+/* Add more spacing between API sections */
+.doc-heading {
+    margin-top: 1em;
+    border-top: 1px solid var(--md-default-fg-color--lightest);
+    font-size: 0.85rem;
+}
+
+/* Make method names more prominent */
+.doc-method, .doc-function {
+    background-color: var(--md-code-bg-color);
+    padding: 0.1em;
+    margin: 0.5em 0;
+    border-radius: 4px;
+}
+
+/* Make class documentation stand out */
+.doc-class {
+    padding: 1em;
+    margin: 1em 0;
+    border-left: 4px solid var(--md-primary-fg-color);
+    background-color: var(--md-code-bg-color);
+}
+
+/* Style for type labels */
+.doc-label {
+    font-size: 0.8em;
+    padding: 0.2em 0.6em;
+    border-radius: 4px;
+    background-color: var(--md-code-bg-color);
+    display: inline-block;
+    margin: 0.2em 0;
+    font-weight: 400;
+    text-transform: none;  /* Prevent uppercase transformation */
+    color: var(--md-code-fg-color);
+}
+
+/* Add indentation and visual cues for nested navigation items */
+.md-nav__item .md-nav__item {
+    padding-left: 0.3rem;
+    border-left: 1px solid var(--md-primary-fg-color--light);
+    margin-left: 0.2rem;
+}
+
+/* Add some spacing between items */
+.md-nav__item {
+    margin: 0.3em 0;  /* Reduced from 0.4em */
+}
+
+/* Optional: add hover effect */
+.md-nav__item .md-nav__item:hover {
+    border-left-color: var(--md-primary-fg-color);
+}
+
+
+/* Enhance code examples in documentation */
+.highlight {
+    background-color: #f8f9fa;
+    border: 1px solid #e9ecef;
+    border-radius: 6px;
+    margin: 1.5em 0;
+    padding: 1em;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+}
+
+/* Dark mode adjustments */
+[data-md-color-scheme="slate"] .highlight {
+    background-color: #2b2b2b;
+    border-color: #404040;
+}
+
+/* Add subtle left border for visual interest */
+.highlight pre {
+    margin: 0;
+}
+
+/* Ensure code is readable */
+.highlight code {
+    font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+    font-size: 0.9em;
+}
+
+/* Copy button styling */
+.highlight .md-clipboard {
+    color: var(--md-default-fg-color--lighter);
+}
+
+.highlight .md-clipboard:hover {
+    color: var(--md-accent-fg-color);
+}
+
diff --git a/docs/docs/tutorials/agents/index.ipynb → ...ls/compound_ai_systems/agents/index.ipynb b/docs/docs/tutorials/agents/index.ipynb → ...ls/compound_ai_systems/agents/index.ipynb
diff --git a/...s/tutorials/entity_extraction/index.ipynb → ..._ai_systems/entity_extraction/index.ipynb b/...s/tutorials/entity_extraction/index.ipynb → ..._ai_systems/entity_extraction/index.ipynb
diff --git a/docs/docs/tutorials/compound_ai_systems/index.md b/docs/docs/tutorials/compound_ai_systems/index.md
@@ -0,0 +1,9 @@
+# Compound AI Systems
+
+These tutorials demonstrate how to build compound AI systems using DSPy.
+
+- [Retrieval-Augmented Generation](rag/index.ipynb)
+- [Agents](agents/index.ipynb)
+- [Reasoning](math/index.ipynb)
+- [Entity Extraction](entity_extraction/index.ipynb)
+- [Privacy-Conscious Delegation](papillon/index.md)
diff --git a/docs/docs/tutorials/math/index.ipynb → ...ials/compound_ai_systems/math/index.ipynb b/docs/docs/tutorials/math/index.ipynb → ...ials/compound_ai_systems/math/index.ipynb
diff --git a/docs/docs/tutorials/papillon/index.md → ...als/compound_ai_systems/papillon/index.md b/docs/docs/tutorials/papillon/index.md → ...als/compound_ai_systems/papillon/index.md
diff --git a/docs/docs/tutorials/rag/index.ipynb → ...rials/compound_ai_systems/rag/index.ipynb b/docs/docs/tutorials/rag/index.ipynb → ...rials/compound_ai_systems/rag/index.ipynb
diff --git a/...s/tutorials/deployment/dspy_mlflow_ui.png → ...ick_recipes/deployment/dspy_mlflow_ui.png b/...s/tutorials/deployment/dspy_mlflow_ui.png → ...ick_recipes/deployment/dspy_mlflow_ui.png
diff --git a/docs/docs/tutorials/deployment/index.md → ...torials/quick_recipes/deployment/index.md b/docs/docs/tutorials/deployment/index.md → ...torials/quick_recipes/deployment/index.md
diff --git a/docs/docs/tutorials/quick_recipes/index.md b/docs/docs/tutorials/quick_recipes/index.md
@@ -0,0 +1,8 @@
+# Quick DSPy Recipes
+
+These tutorials demonstrate various fundamentals of DSPy, including saving and loading, deployment,
+and debugging tips.
+
+- [Saving and Loading](saving/index.md)
+- [Deployment](deployment/index.md)
+- [Debugging & Observability](observability/index.md)
diff --git a/.../tutorials/observability/dspy-tracing.gif → ...ck_recipes/observability/dspy-tracing.gif b/.../tutorials/observability/dspy-tracing.gif → ...ck_recipes/observability/dspy-tracing.gif
diff --git a/docs/docs/tutorials/observability/index.md → ...ials/quick_recipes/observability/index.md b/docs/docs/tutorials/observability/index.md → ...ials/quick_recipes/observability/index.md
diff --git a/docs/docs/tutorials/saving/index.md → ...s/tutorials/quick_recipes/saving/index.md b/docs/docs/tutorials/saving/index.md → ...s/tutorials/quick_recipes/saving/index.md
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,7 +3,7 @@ sidebar_position: 1 @@
     ---
-    # Optimization in DSPy
+    # Optimize your DSPy program
     Once you have a system and a way to evaluate it, you can use DSPy optimizers to tune the prompts or weights in your program. Now it's useful to expand your data collection effort into building a training set and a held-out test set, in addition to the development set you've been using for exploration. For the training set (and its subset, validation set), you can often get substantial value out of 30 examples, but aim for at least 300 examples. Some optimizers accept a `trainset` only. Others ask for a `trainset` and a `valset`. For prompt optimizers, we suggest starting with a 20% split for training and 80% for validation, which is often the _opposite_ of what one does for DNNs.
@@ Expand Down @@