Merge branch 'main' into claude_3

Author: isaacbmiller

.github/workflows/run_tests.yml

@@ -1,29 +1,38 @@
-name: Fix, Test, and Build
+name: Lint, Test, and Build
 
 on:
   push:
     branches:
       - main
   pull_request:
+    types: [opened, synchronize, reopened]
 
 env:
   POETRY_VERSION: "1.6.1"
 
 jobs:
   fix:
-    name: Apply Ruff Fix
+    name: Check Ruff Fix
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
-      - uses: chartboost/ruff-action@v1
-        with:
-          args: --fix-only
-      - uses: stefanzweifel/git-auto-commit-action@v5
+      - name: Ruff Fix Attempt
+        id: ruff_fix
+        uses: chartboost/ruff-action@v1
         with:
-          commit_message: "Automatic Style fixes"
+          args: --fix-only --exit-non-zero-on-fix
+        continue-on-error: true
+
+      - name: Fail Workflow if Ruff Fix Failed
+        if: steps.ruff_fix.outcome == 'failure'
+        run: |
+          echo "Ruff fix failed, failing the workflow."
+          echo "Please run 'ruff check . --fix-only' locally and push the changes."
+          exit 1
 
   test:
     name: Run Tests
@@ -33,8 +42,6 @@ jobs:
         python-version: ["3.9"]
     steps:
       - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.head_ref }}
       - name: Load cached Poetry installation
         id: cached-poetry
         uses: actions/cache@v3
@@ -66,8 +73,6 @@ jobs:
         python-version: ["3.9"]
     steps:
       - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.head_ref }}
       - name: Load cached Poetry installation
         id: cached-poetry
         uses: actions/cache@v3
@@ -99,8 +104,6 @@ jobs:
         python-version: ["3.9"]
     steps:
       - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.head_ref }}
       - name: Load cached Poetry installation
         id: cached-poetry
         uses: actions/cache@v3

.pre-commit-config.yaml

@@ -5,15 +5,15 @@ default_stages: [commit]
 default_install_hook_types: [pre-commit, commit-msg]
 
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
-    rev: v0.1.11
-    hooks:
-      # Run the linter.
-      - id: ruff
-        args: [--fix]
-      # Run the formatter.
-      - id: ruff-format
+  #  - repo: https://github.com/astral-sh/ruff-pre-commit
+  #    # Ruff version.
+  #    rev: v0.1.11
+  #    hooks:
+  #      # Run the linter.
+  #      - id: ruff
+  #        args: [--fix]
+  #      # Run the formatter.
+  #      - id: ruff-format
 
   - repo: https://github.com/timothycrosley/isort
     rev: 5.12.0
@@ -50,14 +50,14 @@ repos:
         args:
           - "--autofix"
           - "--indent=2"
-  - repo: local
-    hooks:
-      - id: validate-commit-msg
-        name: Commit Message is Valid
-        language: pygrep
-        entry: ^(break|build|ci|docs|feat|fix|perf|refactor|style|test|ops|hotfix|release|maint|init|enh|revert)\([\w,\.,\-,\(,\),\/]+\)(!?)(:)\s{1}([\w,\W,:]+)
-        stages: [commit-msg]
-        args: [--negate]
+  #  - repo: local
+  #    hooks:
+  #      - id: validate-commit-msg
+  #        name: Commit Message is Valid
+  #        language: pygrep
+  #        entry: ^(break|build|ci|docs|feat|fix|perf|refactor|style|test|ops|hotfix|release|maint|init|enh|revert)\([\w,\.,\-,\(,\),\/]+\)(!?)(:)\s{1}([\w,\W,:]+)
+  #        stages: [commit-msg]
+  #        args: [--negate]
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v3.0.3

docs/api/functional/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Functional",
+    "position": 2,
+    "link": {
+      "type": "generated-index",
+      "description": "This documentation provides an overview of the Typed Predictors."
+    }
+}

docs/api/functional/dspy_TypedCoT.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+---
+
+# dspy.TypedChainOfThought
+
+### Overview
+
+#### `def TypedChainOfThought(signature, max_retries=3) -> dspy.Module`
+
+Adds a Chain of Thoughts `dspy.OutputField` to the `dspy.TypedPredictor` module by prepending it to the Signature. Similar to `dspy.TypedPredictor` but automatically adds a "reasoning" output field.
+
+* **Inputs**:
+    * `signature`: The `dspy.Signature` specifying the input/output fields
+    * `max_retries`: Maximum number of retries if outputs fail validation
+* **Output**: A dspy.Module instance capable of making predictions.
+
+### Example
+
+```python
+from dspy import InputField, OutputField, Signature
+from dspy.functional import TypedChainOfThought
+from pydantic import BaseModel
+
+# We define a pydantic type that automatically checks if it's argument is valid python code.
+class CodeOutput(BaseModel):
+    code: str
+    api_reference: str
+
+class CodeSignature(Signature):
+    function_description: str = InputField()
+    solution: CodeOutput = OutputField()
+
+cot_predictor = TypedChainOfThought(CodeSignature)
+prediction = cot_predictor(
+    function_description="Write a function that adds two numbers."
+)
+
+print(prediction["code"])
+print(prediction["api_reference"])
+```

docs/api/functional/dspy_TypedPredictor.md

@@ -0,0 +1,78 @@
+---
+sidebar_position: 1
+---
+
+# dspy.TypedPredictor
+
+The `TypedPredictor` class is a sophisticated module designed for making predictions with strict type validations. It leverages a signature to enforce type constraints on inputs and outputs, ensuring that the data follows to the expected schema.
+
+### Constructor
+
+```python
+TypedPredictor(
+    CodeSignature
+    max_retries=3
+)
+```
+
+Parameters:
+* `signature` (dspy.Signature): The signature that defines the input and output fields along with their types.
+* `max_retries` (int, optional): The maximum number of retries for generating a valid prediction output. Defaults to 3.
+
+### Methods
+
+#### `copy() -> "TypedPredictor"`
+
+Creates and returns a deep copy of the current TypedPredictor instance.
+
+**Returns:** A new instance of TypedPredictor that is a deep copy of the original instance.
+
+#### `_make_example(type_: Type) -> str`
+
+A static method that generates a JSON object example based pn the schema of the specified Pydantic model type. This JSON object serves as an example for the expected input or output format.
+
+**Parameters:**
+* `type_`: A Pydantic model class for which an example JSON object is to be generated.
+
+**Returns:** A string that represents a JSON object example, which validates against the provided Pydantic model's JSON schema. If the method is unable to generate a valid example, it returns an empty string.
+
+#### `_prepare_signature() -> dspy.Signature`
+
+Prepares and returns a modified version of the signature associated with the TypedPredictor instance. This method iterates over the signature's fields to add format and parser functions based on their type annotations.
+
+**Returns:** A dspy.Signature object that has been enhanced with formatting and parsing specifications for its fields.
+
+#### `forward(**kwargs) -> dspy.Prediction`
+
+Executes the prediction logic, making use of the `dspy.Predict` component to generate predictions based on the input arguments. This method handles type validation, parsing of output data, and implements retry logic in case the output does not initially follow to the specified output schema.
+
+**Parameters:**
+
+* `**kwargs`: Keyword arguments corresponding to the input fields defined in the signature.
+
+**Returns:** A dspy.Prediction object containing the prediction results. Each key in this object corresponds to an output field defined in the signature, and its value is the parsed result of the prediction.
+
+### Example
+
+```python
+from dspy import InputField, OutputField, Signature
+from dspy.functional import TypedPredictor
+from pydantic import BaseModel
+
+# We define a pydantic type that automatically checks if it's argument is valid python code.
+class CodeOutput(BaseModel):
+    code: str
+    api_reference: str
+
+class CodeSignature(Signature):
+    function_description: str = InputField()
+    solution: CodeOutput = OutputField()
+
+cot_predictor = TypedPredictor(CodeSignature)
+prediction = cot_predictor(
+    function_description="Write a function that adds two numbers."
+)
+
+print(prediction["code"])
+print(prediction["api_reference"])
+```

docs/api/functional/dspy_cot.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 4
+---
+
+# dspy.cot
+
+### Overview
+
+#### `def cot(func) -> dspy.Module`
+
+The `@cot` decorator is used to create a Chain of Thoughts module based on the provided function. It automatically generates a `dspy.TypedPredictor` and from the function's type annotations and docstring. Similar to predictor, but adds a "Reasoning" output field to capture the model's step-by-step thinking.
+
+* **Input**: Function with input parameters and return type annotation.
+* **Output**: A dspy.Module instance capable of making predictions.
+
+### Example
+
+```python
+import dspy
+
+context = ["Roses are red.", "Violets are blue"]
+question = "What color are roses?"
+
+@dspy.cot
+def generate_answer(self, context: list[str], question) -> str:
+    """Answer questions with short factoid answers."""
+    pass
+
+generate_answer(context=context, question=question)
+```

docs/api/functional/dspy_predictor.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 3
+---
+
+# dspy.predictor
+
+### Overview
+
+#### `def predictor(func) -> dspy.Module`
+
+The `@predictor` decorator is used to create a predictor module based on the provided function. It automatically generates a `dspy.TypedPredictor` and from the function's type annotations and docstring.
+
+* **Input**: Function with input parameters and return type annotation.
+* **Output**: A dspy.Module instance capable of making predictions.
+
+### Example
+
+```python
+import dspy
+
+context = ["Roses are red.", "Violets are blue"]
+question = "What color are roses?"
+
+@dspy.predictor
+def generate_answer(self, context: list[str], question) -> str:
+    """Answer questions with short factoid answers."""
+    pass
+
+generate_answer(context=context, question=question)
+```

docs/api/language_model_clients/_category_.json

@@ -1,6 +1,6 @@
 {
     "label": "Language Model API Clients",
-    "position": 4,
+    "position": 5,
     "link": {
       "type": "generated-index",
       "description": "This documentation provides an overview of the DSPy Language Model Clients."

docs/api/local_language_model_clients/HFModel.md

@@ -0,0 +1,7 @@
+# dspy.HFModel
+
+Initialize `HFModel` within your program with the desired model to load in. Here's an example call:
+
+```python
+llama = dspy.HFModel(model = 'meta-llama/Llama-2-7b-hf')
+```

docs/api/local_language_model_clients/MLC.md

@@ -0,0 +1,41 @@
+# dspy.ChatModuleClient
+
+## Prerequisites
+
+1. Install the required packages using the following commands:
+   
+   ```shell
+   pip install --no-deps --pre --force-reinstall mlc-ai-nightly-cu118 mlc-chat-nightly-cu118 -f https://mlc.ai/wheels
+   pip install transformers
+   git lfs install
+   ```
+   
+   Adjust the pip wheels according to your OS/platform by referring to the provided commands in [MLC packages](https://mlc.ai/package/).
+
+## Running MLC Llama-2 models
+
+1. Create a directory for prebuilt models:
+
+   ```shell
+   mkdir -p dist/prebuilt
+   ```
+   
+2. Clone the necessary libraries from the repository:
+
+   ```shell
+   git clone https://github.com/mlc-ai/binary-mlc-llm-libs.git dist/prebuilt/lib
+   cd dist/prebuilt
+   ```
+   
+3. Choose a Llama-2 model from [MLC LLMs](https://huggingface.co/mlc-ai) and clone the model repository:
+
+   ```shell
+   git clone https://huggingface.co/mlc-ai/mlc-chat-Llama-2-7b-chat-hf-q4f16_1
+   ```
+
+4. Initialize the `ChatModuleClient` within your program with the desired parameters. Here's an example call:
+
+   ```python
+   llama = dspy.ChatModuleClient(model='dist/prebuilt/mlc-chat-Llama-2-7b-chat-hf-q4f16_1', model_path='dist/prebuilt/lib/Llama-2-7b-chat-hf-q4f16_1-cuda.so')
+   ```
+Please refer to the [official MLC repository](https://github.com/mlc-ai/mlc-llm) for more detailed information and [documentation](https://mlc.ai/mlc-llm/docs/get_started/try_out.html).