From 14167c33a6334206d6537af99b1747376d5960fd Mon Sep 17 00:00:00 2001 From: Sergio Bayona Date: Wed, 24 Apr 2024 12:07:31 -0500 Subject: [PATCH] updated docs --- docs/contributing.md | 72 +++++++---------------- docs/guidelines.md | 67 ---------------------- docs/help.md | 6 +- docs/index.md | 87 +++++++++++++--------------- docs/installation.md | 8 +-- docs/why.md | 132 ------------------------------------------- 6 files changed, 64 insertions(+), 308 deletions(-) delete mode 100644 docs/guidelines.md delete mode 100644 docs/why.md diff --git a/docs/contributing.md b/docs/contributing.md index 2ec01aa..d059c16 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,16 +1,16 @@ -We would love for you to contribute to `Instructor-js`. +We would love for you to contribute to `Instructor-rb`. ## Migrating Docs from Python Theres a bunch of examples in the python version, including documentation here [python docs](https://jxnl.github.io/instructor/examples/) -If you want to contribute, please check out [issues](https://github.com/instructor-ai/instructor-js/issues/8) +If you want to contribute, please check out [issues](https://github.com/instructor-ai/instructor/issues) ## Issues -If you find a bug, please file an issue on [our issue tracker on GitHub](https://github.com/instructor-ai/instructor-js/issues). +If you find a bug, please file an issue on [our issue tracker on GitHub](https://github.com/instructor-ai/instructor-rb/issues). -To help us reproduce the bug, please provide a minimal reproducible example, including a code snippet and the full error message. +To help us reproduce the bug, please provide a minimal reproducible example, including a code snippet and the full error message as well as: 1. The `response_model` you are using. 2. The `messages` you are using. @@ -18,15 +18,10 @@ To help us reproduce the bug, please provide a minimal reproducible example, inc --- -# Contribution Guidelines - -This projectuses Bun & Typescript. - ## Environment Setup -### Prerequisites +Ruby 3.2.1 is required to run the project. -- Ensure you have the correct versions of all required runtimes/tools. This project uses a `.tool-versions` file at the root of the repository. If you have [asdf](https://asdf-vm.com/) (a universal version manager), it should automatically pick up the required versions. ### Installation @@ -34,82 +29,55 @@ This projectuses Bun & Typescript. Run the following command to install the project dependencies: ```bash -bun install +bundle install ``` - 2. **Environment Variables**: -Copy the `.example.env` file to `.env` and fill in the necessary values for the OpenAI and Anyscale keys. - -### Code Quality Tools +setup the OpenAI API key in your environment variables. -- This project uses ESLint and Prettier for code formatting and quality checks. -- Prettier is integrated with ESLint, so it's recommended to use an ESLint plugin in your IDE. -- For Visual Studio Code or Cursor users: Project-level settings are configured to enable ESLint autosave. +```bash -The IDE should prompt you to install recommended plugins. +### Code Quality Tools -*Note: If using the Prettier plugin, ensure it's disabled to avoid conflicts. +- This project uses rubocop. ### Running Tests - Execute tests using the following command: ```bash -bun test +bundle exec rspec ``` +### Running the Rubocop - - +```bash +bundle exec rubocop +``` ### Pull Requests We welcome pull requests! There is plenty to do, and we are happy to discuss any contributions you would like to make. -If it is not a small change, please start by [filing an issue](https://github.com/instructor-ai/instructor-js/issues) first. - -If you need ideas, you can check out the [help wanted](https://github.com/instructor-ai/instructor-js/labels/help%20wanted) or [good first issue](https://github.com/instructor-ai/instructor-js/labels/good%20first%20issue) labels. - - - -### Source Code Changes - -- If your PR includes changes to the source code, include a `changeset`. -- Changesets help manage and automate versioning. -- Create a changeset by running `bun changeset` at the root of the project and following the prompts. -- Be descriptive in the changeset as it will be included in the changelog for the next release. -- Choose `patch`, `minor`, or `major` for your changeset depending on the type of change. -- Commit the changeset file (an auto-generated markdown file describing the changes). This will trigger a CI action once merged and stack the change on top of any existing ones in preparation for the next release. - -For more information on changesets, visit: [Changesets GitHub Repository](https://github.com/changesets/changesets) +If it is not a small change, please start by [filing an issue](https://github.com/instructor-ai/instructor-rb/issues) first. ## Community and Support -- Join our community on Discord: [Join Discord](https://discord.gg/CbfxwgHA6y) -- Reach out on Twitter: [@dimitrikennedy](https://twitter.com/dimitrikennedy) [@jxnlco](https://twitter.com/jxnlco) +- Join our community on Discord: [Join Discord](https://discord.gg/DWHZdqpNgz) +- Reach out on Twitter: [@sergiobayona](https://twitter.com/sergiobayona) [@jxnlco](https://twitter.com/jxnlco) ## Contributors - - - - - - - - - - + ## Additional Resources Python is required to run the documentation locally using mkdocs. -To enhance your understanding of the documentation, here are some useful references: +To improve your understanding of the documentation, here are some useful references: - **mkdocs serve:** The `mkdocs serve` command is used to preview your documentation locally during the development phase. When you run this command in your terminal, MkDocs starts a development server, allowing you to view and interact with your documentation in a web browser. This is helpful for checking how your changes look before publishing the documentation. Learn more in the [mkdocs serve documentation](https://www.mkdocs.org/commands/serve/). diff --git a/docs/guidelines.md b/docs/guidelines.md deleted file mode 100644 index 47e61c6..0000000 --- a/docs/guidelines.md +++ /dev/null @@ -1,67 +0,0 @@ - -# Contribution Guidelines - -This document outlines the process and guidelines for contributing to this project, which uses Bun & Typescript. - -## Environment Setup - -### Prerequisites - -- Ensure you have the correct versions of all required runtimes/tools. This project uses a `.tool-versions` file at the root of the repository. If you have [asdf](https://asdf-vm.com/) (a universal version manager), it should automatically pick up the required versions. - -### Installation - -1. **Install Dependencies**: - Run the following command to install the project dependencies: - -```bash -bun install -``` - - -2. **Environment Variables**: -Copy the `.example.env` file to `.env` and fill in the necessary values for the OpenAI and Anyscale keys. - -### Code Quality Tools - -- This project uses ESLint and Prettier for code formatting and quality checks. -- Prettier is integrated with ESLint, so it's recommended to use an ESLint plugin in your IDE. -- For Visual Studio Code or Cursor users: Project-level settings are configured to enable ESLint autosave. - -The IDE should prompt you to install recommended plugins. - -*Note: If using the Prettier plugin, ensure it's disabled to avoid conflicts. - -### Running Tests - -- Execute tests using the following command: - -```bash -bun test -``` - - -## Making Contributions - -### Pull Requests (PRs) - -- Keep PRs focused and scoped to specific changes. -- Provide detailed descriptions in your PRs. Screenshots or videos are excellent ways to enhance communication. - -### Source Code Changes - -- If your PR includes changes to the source code, include a `changeset`. -- Changesets help manage and automate versioning. -- Create a changeset by running `bun changeset` at the root of the project and following the prompts. -- Be descriptive in the changeset as it will be included in the changelog for the next release. -- Choose `patch`, `minor`, or `major` for your changeset depending on the type of change. -- Commit the changeset file (an auto-generated markdown file describing the changes). This will trigger a CI action once merged and stack the change on top of any existing ones in preparation for the next release. - -For more information on changesets, visit: [Changesets GitHub Repository](https://github.com/changesets/changesets) - ---- - -## Community and Support - -- Join our community on Discord: [Join Discord](https://discord.gg/CbfxwgHA6y) -- Reach out on Twitter: [@dimitrikennedy](https://twitter.com/dimitrikennedy)[@jxnlco](https://twitter.com/jxnlco) diff --git a/docs/help.md b/docs/help.md index b5e1a1c..6aeb023 100644 --- a/docs/help.md +++ b/docs/help.md @@ -9,7 +9,7 @@ If you need help getting started with Instructor or with advanced usage, the fol ## :fontawesome-brands-discord: Discord -The [Discord](https://discord.gg/CV8sPM5k5Y) is the best place to get help. You can ask questions, get help with debugging, and discuss Instructor with other users. +The [Discord](https://discord.gg/DWHZdqpNgz) is the best place to get help. You can ask questions, get help with debugging, and discuss Instructor with other users. ## :material-creation: Concepts @@ -21,11 +21,11 @@ The [cookbooks](examples/index.md) are a great place to start. They contain a va ## :material-github: GitHub Discussions -[GitHub discussions](https://github.com/instructor-ai/instructor-js/discussions) are useful for asking questions, your question and the answer will help everyone. +[GitHub discussions](https://github.com/instructor-ai/instructor-rb/discussions) are useful for asking questions, your question and the answer will help everyone. ## :material-github: GitHub Issues -[GitHub issues](https://github.com/instructor-ai/instructor-js/issues) are useful for reporting bugs or requesting new features. +[GitHub issues](https://github.com/instructor-ai/instructor-rb/issues) are useful for reporting bugs or requesting new features. ## :material-twitter: Twitter diff --git a/docs/index.md b/docs/index.md index 37c19af..41b7053 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,55 +5,52 @@ _Structured extraction in Typescript, powered by llms, designed for simplicity, --- [![Twitter Follow](https://img.shields.io/twitter/follow/jxnlco?style=social)](https://twitter.com/jxnlco) -[![Twitter Follow](https://img.shields.io/twitter/follow/dimitrikennedy?style=social)](https://twitter.com/dimitrikennedy) -[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://jxnl.github.io/instructor-js) -[![GitHub issues](https://img.shields.io/github/issues/instructor-ai/instructor-js.svg)](https://github.com/instructor-ai/instructor-js/issues) -[![Discord](https://img.shields.io/discord/1192334452110659664?label=discord)](https://discord.gg/CV8sPM5k5Y) +[![Twitter Follow](https://img.shields.io/twitter/follow/sergiobayona?style=social)](https://twitter.com/sergiobayona) +[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://jxnl.github.io/instructor-rb) +[![GitHub issues](https://img.shields.io/github/issues/instructor-ai/instructor-js.svg)](https://github.com/instructor-ai/instructor-rb/issues) +[![Discord](https://img.shields.io/discord/1192334452110659664?label=discord)](https://discord.gg/DWHZdqpNgz) -Dive into the world of Typescript-based structured extraction, by OpenAI's function calling API and Zod, typeScript-first schema validation with static type inference. Instructor stands out for its simplicity, transparency, and user-centric design. Whether you're a seasoned developer or just starting out, you'll find Instructor's approach intuitive and steerable. +Dive into the world of Ruby-based structured extraction, by OpenAI's function calling API, Ruby schema validation with type hinting. Instructor stands out for its simplicity, transparency, and user-centric design. Whether you're a seasoned developer or just starting out, you'll find Instructor's approach intuitive and steerable. -Check us out in [Python](https://jxnl.github.io/instructor/), [Elixir](https://github.com/thmsmlr/instructor_ex/) and [PHP](https://github.com/cognesy/instructor-php/). +Check us out in [Python](https://jxnl.github.io/instructor/), [Elixir](https://github.com/thmsmlr/instructor_ex/), [PHP](https://github.com/cognesy/instructor-php/) and [Ruby](https://github.com/instructor-ai/instructor-rb). If you want to port Instructor to another language, please reach out to us on [Twitter](https://twitter.com/jxnlco) we'd love to help you get started! ## Usage -To check out all the tips and tricks to prompt and extract data, check out the [documentation](https://instructor-ai.github.io/instructor-js/tips/prompting/). - -```ts -import Instructor from "@instructor-ai/instructor"; -import OpenAI from "openai" -import { z } from "zod" - -const oai = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY ?? undefined, - organization: process.env.OPENAI_ORG_ID ?? undefined -}) - -const client = Instructor({ - client: oai, - mode: "FUNCTIONS" -}) - -const UserSchema = z.object({ - // Description will be used in the prompt - age: z.number().describe("The age of the user"), - name: z.string() -}) - - -// User will be of type z.infer -const user = await client.chat.completions.create({ - messages: [{ role: "user", content: "Jason Liu is 30 years old" }], - model: "gpt-3.5-turbo", - response_model: { - schema: UserSchema, - name: "User" - } -}) - -console.log(user) -// { age: 30, name: "Jason Liu" } +To check out all the tips and tricks to prompt and extract data, check out the [documentation](https://instructor-ai.github.io/instructor-rb/tips/prompting/). + +```Ruby +require 'instructor-rb' + +OpenAI.configure do |config| + config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN") + config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional. +end + +class UserDetail + include EasyTalk::Model + + define_schema do + property :name, String + property :age, Integer + end +end + +client = Instructor.patch(OpenAI::Client).new + +user = client.chat( +parameters: { + model: 'gpt-3.5-turbo', + messages: [{ role: 'user', content: 'Extract Jason is 25 years old' }] +}, +response_model: UserDetail +) + +user.name +# => "Jason" +user.age +# => 25 ``` ## Why use Instructor? @@ -62,11 +59,7 @@ The question of using Instructor is fundamentally a question of why to use zod. 1. **Powered by OpenAI** — Instructor is powered by OpenAI's function calling API. This means you can use the same API for both prompting and extraction. -2. **Customizable** — Zod is highly customizable. You can define your own validators, custom error messages, and more. - -3. **Ecosystem** Zod is the most widely used data validation library for Typescript. - -4. **Battle Tested** — Zod is downloaded over 24M times per month, and supported by a large community of contributors. +2. **Ruby Schema Validation** — Instructor uses Ruby schema validation with type hinting. This means you can validate your data before using it. ## More Examples diff --git a/docs/installation.md b/docs/installation.md index 878adef..c2d9c3a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,11 +1,5 @@ Installation is as simple as: ```bash -npm install @instructor-ai/instructor openai zod +gem install intructor-rb ``` - -Instructor-js has a few dependencies: - -- [`openai`](https://www.npmjs.com/package/openai): OpenAI's TypeScript / JavaScript library. -- [`zod`](https://www.npmjs.com/package/zod): TypeScript-first schema validation with static type inference. - diff --git a/docs/why.md b/docs/why.md deleted file mode 100644 index 6617cdc..0000000 --- a/docs/why.md +++ /dev/null @@ -1,132 +0,0 @@ -# Why use Instructor? - -??? question "Why use Zod?" - - Its hard to answer the question of why use Instructor without first answering [why use Zod.](https://zod.dev/?id=introduction): - - - - **Powered by OpenAI** — Instructor is powered by OpenAI's function calling API. This means you can use the same API for both prompting and extraction. - - - **Customization** — Zod is highly customizable. You can define your own validators, custom error messages, and more. - - - **Ecosystem** — Zod is the most widely used data validation library for Typescript. - - - **Battle tested** — Zod is downloaded over 24M times/month and is supported by a large community of contributors. If you're trying to do something with Zod, someone else has probably already done it. - -Our `Instructor` client for the `OpenAI` class introduces three key enhancements: - -- **Response Mode:** Specify a Zod model to streamline data extraction. -- **Max Retries:** Set your desired number of retry attempts for requests. -- **Validation Context:** Provide a context object for enhanced validator access. - A Glimpse into Instructor's Capabilities - -!!! note "Using Validators" - - Learn more about validators checkout our blog post [Good llm validation is just good validation](https://jxnl.github.io/instructor/blog/2023/10/23/good-llm-validation-is-just-good-validation/) - -With Instructor, your code becomes more efficient and readable. Here’s a quick peek: - -## Understanding the `Instructor` class - -Lets go over the `Instructor` class. And see how we can leverage it to make use of instructor - -### Step 1: Patch the OpenAI client - -First, import the required libraries and construct the Instructor class by passing in the OpenAI client. This exposes new functionality with the `response_model` parameter. - -```ts -import Instructor from "@instructor-ai/instructor"; -import OpenAI from "openai" -import { z } from "zod" - -// Create the OpenAI client -const oai = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY ?? undefined, - organization: process.env.OPENAI_ORG_ID ?? undefined, -}) - -// This enables response_model keyword -// from client.chat.completions.create -const client = Instructor({ - client: oai, - mode: "FUNCTIONS" -}) -``` - -### Step 2: Define the Zod Model - -Create a Zod model to define the structure of the data you want to extract. This model will map directly to the information in the prompt. - -```ts -import { z } from "zod" - -const UserSchema = z.object({ - age: z.number(), - name: z.string(), -}) - -type User = z.infer -``` - -### Step 3: Extract - -Use the `client.chat.completions.create` method to send a prompt and extract the data into the Zod object. The `response_model` parameter specifies the Zod schema to use for extraction. Its helpful to annotate the variable with the type of the response model, which will help your IDE provide autocomplete and spell check. - -```ts - -const user = await client.chat.completions.create({ - messages: [{ role: "user", content: "Jason Liu is 30 years old" }], - model: "gpt-3.5-turbo", - response_model: { schema: UserSchema } -}) - -console.log(user) -// { age: 30, name: "Jason Liu" } -``` - -## Understanding Validation - -!!! warning "This section is a work in progress" - - This section is a work in progress. Consider contributing by opening a PR. - -## Self Correcting on Validation Error - -Here, the `UserDetails` Zod schema is passed as the `response_model`, and `max_retries` is set to 2. - -```ts -import Instructor from "@instructor-ai/instructor"; -import OpenAI from "openai" -import { z } from "zod" - -const oai = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY ?? undefined, - organization: process.env.OPENAI_ORG_ID ?? undefined, -}) - -// Apply the patch to the OpenAI client -const client = Instructor({ - client: oai, - mode: "FUNCTIONS" -}) - -// Use refine to ensure the name is uppercase -const UserDetails = z.object({ - age: z.number(), - name: z.string().refine((v) => v.toUpperCase() === v, { - message: "Name must be in uppercase.", - } -}) - -const user = await client.chat.completions.create({ - messages: [{ role: "user", content: "Extract jason is 30 years old" }], - model: "gpt-3.5-turbo", - response_model: { schema: UserDetails }, - max_retries: 2, -}) - -console.log(user.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 including a lot of extra code or prompts. \ No newline at end of file