instructor-rb 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65a1936ae4e512d2ec6606f592ef35be36dbf80b2013abe099056ab3048f5c7d
-  data.tar.gz: d094e3894f65f1d0062be5cfbd8e3c07bb9572f62e78425990e64c2c46e78425
+  metadata.gz: c5f3b630f135c5ab67b275814d8986b732a0deac2a8cb751189444d5774ab169
+  data.tar.gz: cc25330573de9056fdf7e6c5f14d4fb143777b9f26a7d085e00499df6610c8da
 SHA512:
-  metadata.gz: 1b2eb9e6ad25aabe51a7e04d6fae1526228c362608daf00608aa0035577981e21fbe091fe138f7e09f3d9d58f062ab5f6bdc0ae77f7c88de2d95564b64191840
-  data.tar.gz: b1faeba25a79bb016becce490488d7cd06bc546ab5e7f9a1ec8c1d6d26ce3ee9115de665625a790f47b6463e280c77f4b9b90f976192e68d9b2b597dd4f88a7d
+  metadata.gz: 90ce22b6ca7bdc23a063b7fcee1329a194cc493b71803902d2455d0c22d105de7506c7387f6b0e7b682405493dc7eb9c7da68e6da68feedb89bdbcbea598cea2
+  data.tar.gz: f6ebf426c755b1d55cb809d75c56a38e5861515419e61e235097c2033729abf8e7e9df200146844c742fcc17fb8b984b4b6cd11d751927a1d93760db321f670c

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [0.1.2] - 2024-05-17
+- Improved the ability to customize the function name and the LLM function call description (instructions).
+
+## [0.1.1] - 2024-05-07
+- Improved documentation in /docs folder.
+- Readme updates.
+- Upgraded EasyTalk (many improvements and bug fixes).
+
+## [0.1.0] - 2024-04-24
+- Initial release

data/README.md

@@ -5,22 +5,32 @@ _Structured extraction in Ruby, powered by llms, designed for simplicity, transp
 ---
 
 [![Twitter Follow](https://img.shields.io/twitter/follow/jxnlco?style=social)](https://twitter.com/jxnlco)
+[![Twitter Follow](https://img.shields.io/twitter/follow/sbayona?style=social)](https://twitter.com/sbayona)
 [![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)
+[![GitHub issues](https://img.shields.io/github/issues/instructor-ai/instructor-rb.svg)](https://github.com/instructor-ai/instructor-rb/issues)
 [![Discord](https://img.shields.io/discord/1192334452110659664?label=discord)](https://discord.gg/CV8sPM5k5Y)
 
-Dive into the world of Ruby-based structured extraction, by OpenAI's function calling API and ActiveRecord, ruby-first schema validation with 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.
+Instructor-rb is a Ruby library that makes it a breeze to work with structured outputs from large language models (LLMs). Built on top of [EasyTalk](https://github.com/sergiobayona/easy_talk), it provides a simple, transparent, and user-friendly API to manage validation, retries, and streaming responses. Get ready to supercharge your LLM workflows!
 
-> ℹ️ **Tip:**  Support in other languages
+# Getting Started
 
-    Check out ports to other languages below:
+  1. Install Instructor-rb at the command prompt if you haven't yet:
+  
+        ```bash
+        $ gem install instructor-rb
+        ```
 
-    - [Python](https://www.github.com/jxnl/instructor)
-    - [TS/JS](https://github.com/instructor-ai/instructor-js/)
-    - [Ruby](https://github.com/instructor-ai/instructor-rb)
-    - [Elixir](https://github.com/thmsmlr/instructor_ex/)
+  2. In your Ruby project, require the gem:
 
-    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!
+        ```ruby
+        require 'instructor'
+        ```
+
+  3. At the beginning of your script, initialize and patch the OpenAI client:
+
+        ```ruby
+        client = Instructor.patch(OpenAI::Client)
+        ```
 
 ## Usage
 
@@ -30,7 +40,7 @@ export your OpenAI API key:
 export OPENAI_API_KEY=sk-...
 ```
 
-Then use Instructor to extract structured data from text in Ruby:
+Then use Instructor by defining your schema in Ruby using the `define_schema` block and [EasyTalk](https://github.com/sergiobayona/easy_talk)'s schema definition syntax. Here's an example in:
 
 ```ruby
 require 'instructor'
@@ -54,24 +64,33 @@ user = client.chat(
   response_model: UserDetail
 )
 
-puts(user.inspect)
-{"name"=>"Jason", "age"=>25}
+user.name
+# => "Jason"
+user.age
+# => 25
+
 ```
 
-## Why use Instructor?
+  
+> ℹ️ **Tip:**  Support in other languages
 
+    Check out ports to other languages below:
 
-1. **OpenAI Integration** — Integrates seamlessly with OpenAI's API, facilitating efficient data management and manipulation.
+    - [Python](https://www.github.com/jxnl/instructor)
+    - [TS/JS](https://github.com/instructor-ai/instructor-js/)
+    - [Ruby](https://github.com/instructor-ai/instructor-rb)
+    - [Elixir](https://github.com/thmsmlr/instructor_ex/)
 
-2. **Customizable** — It offers significant flexibility. Users can tailor validation processes and define unique error messages.
+    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!
+
+## Why use Instructor?
 
-3. **Widespread Adoption** — As a primary component in Ruby on Rails, it's widely used and backed by a substantial community.
 
-4. **Tested and Trusted** — Its reliability is proven by extensive real-world application, underscored by its high adoption rate in Ruby-based projects.
+1. **OpenAI Integration** — Integrates seamlessly with OpenAI's API, facilitating efficient data management and manipulation.
 
-## More Examples
+2. **Customizable** — It offers significant flexibility. Users can tailor validation processes and define unique error messages.
 
-If you'd like to see more check out our [cookbook](examples/index.md).
+3. **Tested and Trusted** — Its reliability is proven by extensive real-world application.
 
 [Installing Instructor](installation.md) is a breeze. 
 

data/docs/blog/.authors.yml

@@ -0,0 +1,11 @@
+authors:
+  jxnl:
+    name: Jason Liu
+    description: Creator
+    avatar: https://avatars.githubusercontent.com/u/4852235?v=4
+    url: https://twitter.com/intent/follow?screen_name=jxnlco
+  sergiobayona:
+    name: Sergio Bayona
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/155783?v=4
+    url: https://twitter.com/intent/follow?screen_name=sergiobayona

data/docs/blog/index.md

@@ -0,0 +1,3 @@
+# Welcome to the Instructor Blog
+
+If you wanted to check out the main blog check us out [here](https://jxnl.github.io/instructor/blog/) where we have a bunch of posts about Instructor and OpenAI, and how to think about building with structured prompting. This blog will be more focused on the technical details of the Ruby library.

data/docs/concepts/patching.md

@@ -0,0 +1,14 @@
+# Patching
+
+Instructor enhances the client functionality with three new arguments for backwards compatibility. This allows use of the enhanced client as usual, with structured output benefits.
+
+- `response_model`: Defines the response type for `chat`.
+- `max_retries`: Determines retry attempts for failed `chat` validations.
+- `validation_context`: Provides extra context to the validation process.
+
+Instructor-rb only supports the 'tools' mode at the moment. Other modes will be added in the near future.
+
+## Tool Calling
+
+This is the recommended method for OpenAI clients. Since tools is the default and only mode currently supported, there is no `mode:` argument available. It "just works" with the patched client.
+

data/docs/concepts/philosophy.md

@@ -0,0 +1,40 @@
+# Philosophy
+
+The instructor values [simplicity](https://eugeneyan.com/writing/simplicity/) and flexibility in leveraging language models (LLMs). It offers a streamlined approach for structured output, avoiding unnecessary dependencies or complex abstractions. Let [EasyTalk](https://github.com/sergiobayona/easy_talk) do the heavy lifting.
+
+> “Simplicity is a great virtue but it requires hard work to achieve it and education to appreciate it. And to make matters worse: complexity sells better.” — Edsger Dijkstra
+
+## The Bridge to Object-Oriented Programming
+
+`instructor` acts as a bridge converting text-based LLM interactions into a familiar object-oriented format. Its integration with EasyTalk provides type hints, and runtime validation. By treating LLMs as methods returning typed objects, instructor makes [language models backwards compatible with code](https://www.youtube.com/watch?v=yj-wSRJwrrc), making them practical for everyday use while being complex enough for advanced applications.
+
+## The zen of `instructor`
+
+Maintain the flexibility and power of Ruby, without unnecessary constraints.
+
+Begin with a method and a return type hint – simplicity is key. With my experience maintaining a large enterprize framework at my previous job over many years I've learned that the goal of a making a useful framework is minimizing regret, both for the author and hopefully for the user.
+
+1. Define a Schema 
+```ruby
+class StructuredData
+    include EasyTalk::Model
+end
+```
+2. Define properties and methods on your schema.
+3. Encapsulate all your LLM logic into a function `#!ruby def extract(a)`
+4. Define typed computations against your data with `#!ruby def compute(data: StructuredData)` or call methods on your schema `#!ruby data.compute()`
+
+It should be that simple.
+
+## My Goals
+
+The goal for the library, [documentation](https://instructor-ai.github.io/instructor-rb/), and [blog](https://instructor-ai.github.io/instructor-rb/blog/), is to help you be a better Ruby programmer and as a result a better AI engineer.
+
+- The library is a result of my desire for simplicity.
+- The library should help maintain simplicity in your codebase.
+- I won't try to write prompts for you,
+- I don't try to create indirections or abstractions that make it hard to debug in the future
+
+Please note that the library is designed to be adaptable and open-ended, allowing you to customize and extend its functionality based on your specific requirements. If you have any further questions or ideas hit me up on [twitter](https://twitter.com/jxnlco)
+
+Cheers!

data/docs/concepts/schema.md

@@ -0,0 +1,105 @@
+# EasyTalk Schemas 
+
+EasyTalk is a Ruby library for describing, generating and validating JSON Schema. 
+
+## Basic Usage
+
+```Ruby
+
+  class UserDetail
+    include EasyTalk::Model
+
+    define_schema do
+      property :name, String
+      property :age, Integer
+    end
+  end
+```
+
+## Descriptions are Prompts
+
+One of the core things about instructors is that it's able to use these descriptions as part of the prompt. 
+
+```Ruby
+  class UserDetail
+    include EasyTalk::Model
+
+    define_schema do
+      description 'Fully extracted user detail'
+      property :name, String, description: 'Your full name'
+      property :age, Integer
+    end
+  end
+```
+
+## Model Composition
+
+EasyTalk models can themselves be composed of other models.
+
+```Ruby
+  class Address
+    include EasyTalk::Model
+
+    define_schema do
+      property :street, String
+      property :city, String
+    end
+  end
+
+  class UserDetail
+    include EasyTalk::Model
+
+    define_schema do
+      property :name, String
+      property :address, Address
+    end
+  end
+
+```
+
+## Default Values
+
+In order to help the language model, we can also define defaults for the values.
+
+```Ruby
+  class UserDetail
+    include EasyTalk::Model
+
+    define_schema do
+      property :name, String
+      property :is_student, Boolean, default: false
+    end
+  end
+
+```
+## Arrays
+
+Arrays can be defined using the `T::Array[]` method.
+
+```Ruby
+  class UserDetail
+    include EasyTalk::Model
+
+    define_schema do
+      property :name, String
+      property :friends, T::Array[String]
+    end
+  end
+
+```
+
+## Enums 
+
+Enums can be defined using the `enum` constraint.
+
+```Ruby
+  class UserDetail
+    include EasyTalk::Model
+
+    define_schema do
+      property :name, String
+      property :role, String, enum: %w[admin user]
+    end
+  end
+
+```

data/docs/contributing.md

@@ -0,0 +1,90 @@
+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/issues)
+
+## 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 as well as:
+
+1. The `response_model` you are using.
+2. The `messages` you are using.
+3. The `model` you are using.
+
+---
+
+## Environment Setup
+
+Ruby 3.2.1 is required to run the project.
+
+
+### Installation
+
+1. **Install Dependencies**:
+   Run the following command to install the project dependencies:
+
+```bash
+bundle install
+```
+
+2. **Environment Variables**:
+setup the OpenAI API key in your environment variables.
+
+```bash
+
+### Code Quality Tools
+
+- This project uses rubocop.
+
+### Running Tests
+
+- Execute tests using the following command:
+
+```bash
+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-rb/issues) first.
+
+
+## Community and Support
+
+- 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
+
+<a href="https://github.com/jxnl/instructor/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=instructor-ai/instructor-rb" />
+</a>
+
+
+## Additional Resources
+Python is required to run the documentation locally using mkdocs.
+
+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/).
+
+- **hl_lines in Code Blocks:** The `hl_lines` feature in code blocks allows you to highlight specific lines within the code block. This is useful for drawing attention to particular lines of code when explaining examples or providing instructions. You can specify the lines to highlight using the `hl_lines` option in your code block configuration. For more details and examples, you can refer to the [hl_lines documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#syntax-highlighting).
+
+- **Admonitions:** Admonitions are a way to visually emphasize or call attention to certain pieces of information in your documentation. They come in various styles, such as notes, warnings, tips, etc. Admonitions provide a structured and consistent way to present important content. For usage examples and details on incorporating admonitions into your documentation, you can refer to the [admonitions documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#admonitions).
+
+For more details about the documentation structure and features, refer to the [MkDocs Material documentation](https://squidfunk.github.io/mkdocs-material/).
+  
+Thank you for your contributions, and happy coding!

data/docs/examples/action_items.md

@@ -0,0 +1,163 @@
+# Example: Extracting Action Items from Meeting Transcripts
+
+In this guide, we'll walk through how to extract action items from meeting transcripts using OpenAI's API. This use case is a good example for automating project management tasks, such as task assignment and priority setting.
+
+!!! tips "Motivation"
+
+    Significant amount of time is dedicated to meetings, where action items are generated as the actionable outcomes of these discussions. Automating the extraction of action items can save time and guarantee that no critical tasks are overlooked.
+
+## Defining the Structures
+
+We'll model a meeting transcript as a collection of **`Ticket`** objects, each representing an action item. Every **`Ticket`** can have multiple **`Subtask`** objects, representing smaller, manageable pieces of the main task.
+
+```Ruby
+  class Subtask
+    include EasyTalk::Model
+
+    define_schema do
+      property :id, Integer, description: 'Unique identifier for the subtask'
+      property :name, String, description: 'Informative title of the subtask'
+    end
+  end
+
+  class Ticket
+    include EasyTalk::Model
+
+    PRIORITY = %w[low medium high].freeze
+
+    define_schema do
+      property :id, Integer, description: 'Unique identifier for the ticket'
+      property :name, String, description: 'Title of the ticket'
+      property :description, String, description: 'Detailed description of the ticket'
+      property :priority, String, description: 'Priority level'
+      property :assignees, T::Array[String], description: 'List of users assigned to the ticket'
+      property :subtasks, T.nilable(T::Array[Subtask]), description: 'List of subtasks associated with the ticket'
+      property :dependencies, T.nilable(T::Array[Integer]),
+               description: 'List of ticket IDs that this ticket depends on'
+    end
+  end
+
+  class ActionItems
+    include EasyTalk::Model
+
+    define_schema do
+      property :items, T::Array[Ticket]
+    end
+  end
+```
+
+## Extracting Action Items
+
+To extract action items from a meeting transcript, we use the **`extract_action_items()`** method. It calls OpenAI's API, processes the text, and returns a set of action items modeled as **`ActionItems`**.
+
+```Ruby
+
+  def extract_action_items(data)
+    client = Instructor.patch(OpenAI::Client).new
+
+    client.chat(
+      parameters: {
+        model: 'gpt-3.5-turbo',
+        messages: [
+          {
+            role: 'system',
+            "content": 'The following is a transcript of a meeting between a manager and their team. The manager is assigning tasks to their team members and creating action items for them to complete.'
+          },
+          {
+            "role": 'user',
+            "content": "Create the action items for the following transcript: #{data}"
+          }
+        ]
+      },
+      response_model: ActionItems
+    )
+  end
+```
+
+## Evaluation and Testing
+
+To test the **`extract_action_items`** method, we provide it with a sample transcript, and then print the JSON representation of the extracted action items.
+
+```Ruby
+   data = <<~DATA
+      Alice: Hey team, we have several critical tasks we need to tackle for the upcoming release. First, we need to work on improving the authentication system. It's a top priority.
+
+      Bob: Got it, Alice. I can take the lead on the authentication improvements. Are there any specific areas you want me to focus on?
+
+      Alice: Good question, Bob. We need both a front-end revamp and back-end optimization. So basically, two sub-tasks.
+
+      Carol: I can help with the front-end part of the authentication system.
+
+      Bob: Great, Carol. I'll handle the back-end optimization then.
+
+      Alice: Perfect. Now, after the authentication system is improved, we have to integrate it with our new billing system. That's a medium priority task.
+
+      Carol: Is the new billing system already in place?
+
+      Alice: No, it's actually another task. So it's a dependency for the integration task. Bob, can you also handle the billing system?
+
+      Bob: Sure, but I'll need to complete the back-end optimization of the authentication system first, so it's dependent on that.
+
+      Alice: Understood. Lastly, we also need to update our user documentation to reflect all these changes. It's a low-priority task but still important.
+
+      Carol: I can take that on once the front-end changes for the authentication system are done. So, it would be dependent on that.
+
+      Alice: Sounds like a plan. Let's get these tasks modeled out and get started.
+    DATA
+
+    result = generate(data)
+    puts(result.as_json)
+```
+
+## Visualizing the tasks
+
+In order to quickly visualize the data we used code interpreter to create a graphviz export of the json version of the ActionItems array.
+
+![action items](action_items.png)
+
+```json
+{
+  "items": [
+    {
+      "id": 1,
+      "name": "Improve Authentication System",
+      "description": "Revamp the front-end and optimize the back-end of the authentication system",
+      "priority": "High",
+      "assignees": ["Bob", "Carol"],
+      "subtasks": [
+        {
+          "id": 2,
+          "name": "Front-end Revamp"
+        },
+        {
+          "id": 3,
+          "name": "Back-end Optimization"
+        }
+      ],
+      "dependencies": []
+    },
+    {
+      "id": 4,
+      "name": "Integrate Authentication System with Billing System",
+      "description": "Integrate the improved authentication system with the new billing system",
+      "priority": "Medium",
+      "assignees": ["Bob"],
+      "subtasks": [],
+      "dependencies": [1]
+    },
+    {
+      "id": 5,
+      "name": "Update User Documentation",
+      "description": "Update the user documentation to reflect the changes in the authentication system",
+      "priority": "Low",
+      "assignees": ["Carol"],
+      "subtasks": [],
+      "dependencies": [2]
+    }
+  ]
+}
+```
+
+In this example, the **`extract_action_items`** method successfully identifies and segments the action items, assigning them priorities, assignees, subtasks, and dependencies as discussed in the meeting.
+
+By automating this process, you can ensure that important tasks and details are not lost in the sea of meeting minutes, making project management more efficient and effective.

data/docs/examples/classification.md

@@ -0,0 +1,2 @@
+# Classification
+Pending update

data/docs/examples/content_moderation.md

@@ -0,0 +1,2 @@
+# Content Moderation
+pending update

data/docs/examples/index.md

@@ -0,0 +1,18 @@
+# Cookbook
+
+!!! warning "Page under construction"
+
+    This page is under construction. Please check back later. Consider contributing to this page by opening a PR! 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)
+
+
+
+## Table of Contents
+
+- [How do I do classification?](./classification.md)
+- [How are complex queries decomposed into subqueries for a single request?](./query_decomposition.md)
+- [How are action items and dependencies generated from transcripts?](./action_items.md)
+- [How is AI self-assessment implemented with llm_validator?](./self_correction.md)
+- [How are exact citations retrieved using regular expressions and smart prompting?](./validated_citations.md)
+- [How to enable OpenAI's moderation](./content_moderation.md)

data/docs/examples/query_decomposition.md

@@ -0,0 +1,2 @@
+# Query Decomposition
+Pending update

data/docs/examples/self_correction.md

@@ -0,0 +1,2 @@
+# Self Correction
+Pending update

data/docs/examples/validated_citations.md

@@ -0,0 +1,2 @@
+# Validated Citations
+Pending update

data/docs/help.md

@@ -0,0 +1,32 @@
+!!! warning "Page under construction"
+
+    This page is under construction. Please check back later. Consider contributing to this page by opening a PR! 
+
+
+# Getting help with Instructor
+
+If you need help getting started with Instructor or with advanced usage, the following sources may be useful.
+
+## :fontawesome-brands-discord: Discord
+
+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
+
+The [concepts](concepts/prompting.md) section explains the core concepts of Instructor and how to prompt with models.
+
+## :material-chef-hat: Cookbooks
+
+The [cookbooks](examples/index.md) are a great place to start. They contain a variety of examples that demonstrate how to use Instructor in different scenarios.
+
+## :material-github: GitHub Discussions
+
+[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-rb/issues) are useful for reporting bugs or requesting new features.
+
+## :material-twitter: Twitter
+
+You can also reach out to me on [Twitter](https://twitter.com/jxnlco) if you have any questions or ideas.

data/docs/index.md

@@ -0,0 +1,76 @@
+# instructor-rb
+
+_Structured extraction in Ruby, powered by llms, designed for simplicity, transparency, and control._
+
+---
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/jxnlco?style=social)](https://twitter.com/jxnlco)
+[![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 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/), [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-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?
+
+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. **Ruby Schema Validation** — Instructor uses Ruby schema validation with type hinting. This means you can validate your data before using it.
+
+## More Examples
+
+If you'd like to see more check out our [cookbook](examples/index.md).
+
+[Installing Instructor](installation.md) is a breeze. 
+
+## Contributing
+
+If you want to help out, checkout some of the issues marked as `good-first-issue` or `help-wanted`. Found [here](https://github.com/instructor-ai/instructor-js/labels/good%20first%20issue). They could be anything from code improvements, a guest blog post, or a new cook book.
+
+## License
+
+This project is licensed under the terms of the MIT License.

data/docs/installation.md

@@ -0,0 +1,5 @@
+Installation is as simple as:
+
+```bash
+gem install intructor-rb
+```

data/docs/overrides/main.html

@@ -0,0 +1,31 @@
+{% extends "base.html" %}
+<script>
+    !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+    posthog.init('phc_bAUjZfg1PI0Ca2IOQCM053Y5873PRZhJ0DvTDbGsN9A',{api_host:'https://p.useinstructor.com'})
+</script>
+
+{% block announce %} For updates follow
+<strong>@jxnlco</strong> on
+<a href="https://twitter.com/jxnlco">
+  <span class="twemoji twitter">
+    {% include ".icons/fontawesome/brands/twitter.svg" %}
+  </span>
+  <strong>Twitter</strong>
+</a>
+and
+<span class="twemoji star">
+  {% include ".icons/fontawesome/solid/star.svg" %}
+</span>
+us on
+<a href="https://www.github.com/instructor-ai/instructor-rb">
+  <span class="twemoji github">
+    {% include ".icons/fontawesome/brands/github.svg" %}
+  </span>
+  <strong>GitHub</strong> </a
+>. If you don't like Ruby, check out the
+<a href="https://www.github.com/jxnl/instructor"><strong>Python</strong></a>,
+<a href="https://github.com/thmsmlr/instructor_ex/">
+  <strong>Elixir</strong>
+</a> and 
+<a href="https://github.com/instructor-ai/instructor-js"><strong>JavaScript</strong></a>
+ports. {% endblock %}

data/lib/instructor/openai/patch.rb

@@ -118,19 +118,29 @@ module Instructor
         {
           type: 'function',
           function: {
-            name: model.name.humanize.titleize,
+            name: generate_function_name(model),
             description: generate_description(model),
             parameters: model.json_schema
           }
         }
       end
 
+      def generate_function_name(model)
+        model.schema.fetch(:title, model.name)
+      end
+
       # Generates the description for the function.
       #
       # @param model [Class] The response model class.
       # @return [String] The generated description.
       def generate_description(model)
-        "Correctly extracted `#{model.name}` with all the required parameters with correct types"
+        if model.respond_to?(:instructions)
+          raise Instructor::Error, 'The instructions must be a string' unless model.instructions.is_a?(String)
+
+          model.instructions
+        else
+          "Correctly extracted `#{model.name}` with all the required parameters with correct types"
+        end
       end
 
       # Checks if the response is iterable.

data/lib/instructor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Instructor
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/mkdocs.yml

@@ -0,0 +1,191 @@
+site_name: Instructor (Ruby)
+site_author: Jason Liu
+site_description: Structured LLM outputs with EasyTalk
+repo_name: instructor
+repo_url: https://github.com/instructor-ai/instructor-rb
+site_url: https://ruby.useinstructor.com/
+edit_uri: edit/main/docs/
+copyright: Copyright © 2024 Jason Liu
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil 
+    view: material/eye
+    theme:
+    admonition:
+      note: octicons/tag-16
+      abstract: octicons/checklist-16
+      info: octicons/info-16
+      tip: octicons/squirrel-16
+      success: octicons/check-16
+      question: octicons/question-16
+      warning: octicons/alert-16
+      failure: octicons/x-circle-16
+      danger: octicons/zap-16
+      bug: octicons/bug-16
+      example: octicons/beaker-16
+      quote: octicons/quote-16
+  features:
+    - announce.dismiss
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - content.tabs.link
+    - content.tooltips
+    - header.autohide
+    - navigation.expand
+    - navigation.footer
+    - navigation.indexes
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.prune
+    - navigation.sections
+    - navigation.tabs
+    # - navigation.tabs.sticky
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
+    # - toc.integrate
+  palette:
+      - scheme: default
+        primary: black 
+        accent: indigo
+        toggle:
+          icon: material/brightness-7
+          name: Switch to dark mode
+      - scheme: slate
+        primary: black
+        accent: indigo
+        toggle:
+          icon: material/brightness-4
+          name: Switch to light mode
+  font:
+    text: Roboto
+    code: Roboto Mono
+  custom_dir: docs/overrides
+# Extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      normalize_issue_symbols: true
+      repo_url_shorthand: true
+      user: jxnl 
+      repo: instructor
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      auto_append:
+        - includes/mkdocs.md
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+      combine_header_slug: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+nav:
+  - Introduction: 
+    - Welcome To Instructor: 'index.md'
+    - Why use Instructor?: 'why.md'
+    - Schema: 'concepts/schema.md'
+    - Patching: 'concepts/patching.md'
+    - Streaming: 'concepts/streaming.md'
+    - Logging: 'concepts/logging.md'
+    - Prompting Tips: 'tips/prompting.md'
+    - Philosophy: 'concepts/philosophy.md'
+    - Help with Instructor: 'help.md'
+    - Installation: 'installation.md'
+    - Contributing: 'contributing.md'
+  - Cookbook:
+    - Overview: 'examples/index.md'
+    - Classification: 'examples/classification.md'
+    - Query Decomposition: 'examples/query_decomposition.md'
+    - Action Item and Dependency Mapping: 'examples/action_items.md'
+    - Self Correction: 'examples/self_correction.md'
+    - Citing Sources: 'examples/validated_citations.md'
+    - Content Moderation: 'examples/content_moderation.md'
+  - Blog:
+    - "blog/index.md"
+  
+plugins:
+  - social
+  - search:
+      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - minify:
+      minify_html: true
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            members_order: alphabetical
+            allow_inspection: true
+            show_bases: true
+  - blog:
+      enabled: !ENV CI
+      blog_dir: "blog"
+      blog_toc: true
+      post_dir: blog/posts
+      post_date_format: yyyy/MM/dd
+      post_url_format: "{date}/{slug}"
+      authors_file: "{blog}/.authors.yml"
+extra:
+  analytics:
+    provider: google
+    property: G-3JFF533YVZ
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >- 
+            Thanks for your feedback! Help us improve this page by
+            using our <a href="..." target="_blank" rel="noopener">feedback form</a>.
+  social:
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/jxnlco
+    - icon: fontawesome/brands/github
+      link: https://github.com/jxnl
+copyright: Copyright &copy; 2024 Jason Liu

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: instructor-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Sergio Bayona
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-24 00:00:00.000000000 Z
+date: 2024-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -31,14 +31,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.8
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.8
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: ruby-openai
   requirement: !ruby/object:Gem::Requirement
@@ -189,16 +189,36 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile
 - bin/console
+- docs/blog/.authors.yml
+- docs/blog/index.md
+- docs/concepts/patching.md
+- docs/concepts/philosophy.md
+- docs/concepts/schema.md
+- docs/contributing.md
+- docs/examples/action_items.md
+- docs/examples/action_items.png
+- docs/examples/classification.md
+- docs/examples/content_moderation.md
+- docs/examples/index.md
+- docs/examples/query_decomposition.md
+- docs/examples/self_correction.md
+- docs/examples/validated_citations.md
+- docs/help.md
+- docs/index.md
+- docs/installation.md
+- docs/overrides/main.html
 - ellipsis.Dockerfile
 - ellipsis.yaml
 - lib/instructor.rb
 - lib/instructor/openai/patch.rb
 - lib/instructor/openai/response.rb
 - lib/instructor/version.rb
+- mkdocs.yml
 homepage: https://github.com/instructor-ai/instructor-rb
 licenses:
 - MIT