Improve Documentation #189
Conversation
|
Warning Rate Limit Exceeded@jxnl has exceeded the limit for the number of files or commits that can be reviewed per hour. Please wait 15 minutes and 15 seconds before requesting another review. How to resolve this issue?After the wait time has elapsed, a review can be triggered using the @coderabbitai review command. Alternatively, push new commits to this PR. We recommend that you space out your commits to avoid hitting the rate limit. How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. ## Walkthrough
The documentation for the "Instructor" project has undergone a series of updates. Changes include hyperlink updates, text content revisions, code logic alterations, and the addition of new sections and guidelines. The focus seems to be on improving clarity, enhancing user guidance, and streamlining information about the Instructor tool and its integration with Pydantic and OpenAI.
## Changes
| File Path | Change Summary |
|-----------|----------------|
| `docs/blog/posts/chain-of-density.md` | Updated hyperlinks to new relative paths. |
| `docs/concepts/prompting.md` <br> `docs/concepts/reask_validation.md` | Text content revisions, code logic changes, and updated references. |
| `docs/contributing.md` <br> `docs/help.md` | Added new sections for contribution guidelines and getting help. |
| `docs/index.md` <br> `docs/why.md` | Significant content rephrasing, new sections added, and removal of specific code examples. |
| `docs/installation.md` | Added installation instructions for the "instructor" package. |
| `requirements.txt` | Removed `pytest` dependency. |
> 🐇 In the brisk November air, we hop and tweak, 🍂
> Code and docs align, as the updates peak. 📝
> With each commit and push, our project grows,
> A symphony of changes, in the code it shows. 🎶TipsChat with CodeRabbit Bot (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Status
Actionable comments generated: 6
Configuration used: CodeRabbit UI
Files ignored due to filter (1)
- mkdocs.yml
Files selected for processing (9)
- docs/blog/posts/chain-of-density.md (2 hunks)
- docs/concepts/prompting.md (4 hunks)
- docs/concepts/reask_validation.md (3 hunks)
- docs/contributing.md (1 hunks)
- docs/help.md (1 hunks)
- docs/index.md (3 hunks)
- docs/installation.md (1 hunks)
- docs/why.md (1 hunks)
- requirements.txt (1 hunks)
Files skipped from review due to trivial changes (6)
- docs/blog/posts/chain-of-density.md
- docs/concepts/reask_validation.md
- docs/contributing.md
- docs/help.md
- docs/installation.md
- requirements.txt
Additional comments: 12
docs/concepts/prompting.md (3)
1-4: The introduction of the document sets the stage for the use of Instructor and Pydantic, emphasizing modularity and self-description. The changes here seem to be focused on improving the clarity of the documentation.
37-40: The removal of the
rolefield and its replacement with anOptional[str]type indicates a change in the model's design. This change should be verified across the codebase to ensure that all references to therolefield are updated accordingly. Additionally, the use ofOptionalaligns with the best practice of explicitly handling nullable fields.135-138: The change from a
propertiesfield to aList[Property]indicates a shift from a single property to handling multiple properties. This is a logical change that enhances the model's flexibility in handling various user attributes. However, it's crucial to ensure that the code consuming this model is updated to iterate over the list of properties instead of accessing a single property.docs/index.md (3)
1-16: The introduction has been rephrased to be more engaging and informative. The addition of badges for Pydantic, Twitter, downloads, GitHub stars, documentation, and issues provides quick access to relevant resources and social proof, which can be beneficial for the project's visibility and credibility.
69-81: The "Why use Instructor?" section succinctly outlines the benefits of using Instructor with Pydantic, emphasizing ease of use, integration with OpenAI's API, customizability, ecosystem support, and reliability. This section effectively communicates the value proposition of Instructor.
85-87: The reference to the "cookbook" for more examples is a good way to keep the main documentation page clean while still providing users with the resources to learn more. The installation instruction is concise and clear.
docs/why.md (6)
1-19: The introduction to the "Why use Instructor?" section provides a good overview of the benefits of using Pydantic, which is relevant to understanding the value proposition of the Instructor library. The bullet points are informative and concise.
21-25: The enhancements introduced by the
instructor.patchare clearly listed and seem to add valuable functionality to theOpenAIclass. It's important to ensure that these features are well-documented elsewhere in the documentation so that users can understand how to use them effectively.30-30: The hyperlink provided should be verified to ensure it points to the correct URL and that the content is live and relevant to the topic of validators.
52-62: Defining a Pydantic model is well-explained, and the example is straightforward. This should help users understand how to map their data to a model.
66-80: The code snippet demonstrates how to use the patched
OpenAIclient with a Pydantic model. The comments are helpful, but it would be good to ensure that theclient.chat.completions.createmethod is correctly implemented in theinstructorlibrary and that it supports theresponse_modelparameter as shown.117-149: The self-correcting mechanism is an interesting feature. The example provided shows how to handle validation errors and retry the request. It's important to ensure that the
max_retriesparameter is implemented and works as expected in theinstructorlibrary.
| age: int | ||
| name: str | ||
| role: Role | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Replacing the role field with a Role field that references a Role class is a significant change. This introduces a new level of abstraction and should be checked for consistency across the codebase. It's important to ensure that all functions and methods that interact with the UserDetail class are updated to handle this new structure.
docs/index.md
Outdated
| assert user.age == 25 | ||
| ``` | ||
|
|
||
| **"Using `openai<1.0.0`"** | ||
|
|
||
| If you're using `openai<1.0.0` then make sure you `pip install instructor<0.3.0` | ||
| where you can patch a global client like so: | ||
|
|
||
| ```python hl_lines="4 8" | ||
| import openai | ||
| import instructor | ||
|
|
||
| instructor.patch() | ||
|
|
||
| user = openai.ChatCompletion.create( | ||
| ..., | ||
| response_model=UserDetail, | ||
| ) | ||
| ``` | ||
|
|
||
| **"Using async clients"** | ||
| **Using async clients** | ||
|
|
||
| For async clients you must use apatch vs patch like so: |
There was a problem hiding this comment.
The code example provided is clear and demonstrates the usage of Instructor with synchronous code. However, the comment about using apatch for async clients is introduced abruptly. It would be beneficial to either include a full async example here or refer to a section where such an example is provided.
docs/why.md
Outdated
| Lets go over the `patch` function. And see how we can leverage it to make use of instructor | ||
|
|
||
| ### Step 1: Patch the client | ||
|
|
||
| First, import the required libraries and apply the patch function to the OpenAI module. This exposes new functionality with the response_model parameter. | ||
|
|
||
| ```python | ||
| import instructor | ||
| from openai import OpenAI | ||
| from pydantic import BaseModel | ||
|
|
||
| # This enables response_model keyword | ||
| # from client.chat.completions.create | ||
| client = instructor.patch(OpenAI()) | ||
| ``` |
There was a problem hiding this comment.
The explanation of the patch function is clear, but it would be beneficial to include a brief description of what the response_model keyword does and how it enhances the functionality of the OpenAI class.
docs/why.md
Outdated
| Validation can also be plugged into the same Pydantic model. Here, if the answer attribute contains content that violates the rule "don't say objectionable things," Pydantic will raise a validation error. | ||
|
|
||
| ```python hl_lines="9 15" | ||
| from pydantic import BaseModel, ValidationError, BeforeValidator | ||
| from typing_extensions import Annotated | ||
| from instructor import llm_validator | ||
|
|
||
| class QuestionAnswer(BaseModel): | ||
| question: str | ||
| answer: Annotated[ | ||
| str, | ||
| BeforeValidator(llm_validator("don't say objectionable things")) | ||
| ] | ||
|
|
||
| try: | ||
| qa = QuestionAnswer( | ||
| question="What is the meaning of life?", | ||
| answer="The meaning of life is to be evil and steal", | ||
| ) | ||
| except ValidationError as e: | ||
| print(e) | ||
| ``` |
There was a problem hiding this comment.
The validation example is useful for showing how custom validators can be integrated with Pydantic models. However, the highlighted lines in the code snippet (86) do not match the Python syntax and should be removed or corrected.
- ```python hl_lines="9 15"
+ ```python
docs/why.md
Outdated
| Its important to not here that the error message is generated by the LLM, not the code, so it'll be helpful for re asking the model. | ||
|
|
||
| ```plaintext | ||
| 1 validation error for QuestionAnswer | ||
| answer | ||
| Assertion failed, The statement is objectionable. (type=assertion_error) | ||
| ``` |
There was a problem hiding this comment.
The note about the error message being generated by the LLM (Language Learning Model) is insightful, but it should be clarified that the error message is a result of the validation logic defined in the Pydantic model, not directly from the LLM.
docs/why.md
Outdated
| assert model.name == "JASON" | ||
| ``` | ||
|
|
||
| As you can see, we've baked in a self correcting mechanism into the model. This is a powerful way to make your models more robust and less brittle without include a lot of extra code or prompt. |
There was a problem hiding this comment.
The conclusion emphasizes the robustness and simplicity that the Instructor library brings to model validation. It's a strong selling point, but it would be beneficial to have more detailed documentation or examples on how the self-correcting mechanism works in practice.
Address #185 #187
Summary by CodeRabbit
Documentation
Chores
pytestdependency from the requirements, streamlining the package setup.Refactor