instructor-rb 0.1.0 → 0.1.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 65a1936ae4e512d2ec6606f592ef35be36dbf80b2013abe099056ab3048f5c7d
4
- data.tar.gz: d094e3894f65f1d0062be5cfbd8e3c07bb9572f62e78425990e64c2c46e78425
3
+ metadata.gz: c5f3b630f135c5ab67b275814d8986b732a0deac2a8cb751189444d5774ab169
4
+ data.tar.gz: cc25330573de9056fdf7e6c5f14d4fb143777b9f26a7d085e00499df6610c8da
5
5
  SHA512:
6
- metadata.gz: 1b2eb9e6ad25aabe51a7e04d6fae1526228c362608daf00608aa0035577981e21fbe091fe138f7e09f3d9d58f062ab5f6bdc0ae77f7c88de2d95564b64191840
7
- data.tar.gz: b1faeba25a79bb016becce490488d7cd06bc546ab5e7f9a1ec8c1d6d26ce3ee9115de665625a790f47b6463e280c77f4b9b90f976192e68d9b2b597dd4f88a7d
6
+ metadata.gz: 90ce22b6ca7bdc23a063b7fcee1329a194cc493b71803902d2455d0c22d105de7506c7387f6b0e7b682405493dc7eb9c7da68e6da68feedb89bdbcbea598cea2
7
+ data.tar.gz: f6ebf426c755b1d55cb809d75c56a38e5861515419e61e235097c2033729abf8e7e9df200146844c742fcc17fb8b984b4b6cd11d751927a1d93760db321f670c
data/CHANGELOG.md ADDED
@@ -0,0 +1,10 @@
1
+ ## [0.1.2] - 2024-05-17
2
+ - Improved the ability to customize the function name and the LLM function call description (instructions).
3
+
4
+ ## [0.1.1] - 2024-05-07
5
+ - Improved documentation in /docs folder.
6
+ - Readme updates.
7
+ - Upgraded EasyTalk (many improvements and bug fixes).
8
+
9
+ ## [0.1.0] - 2024-04-24
10
+ - Initial release
data/README.md CHANGED
@@ -5,22 +5,32 @@ _Structured extraction in Ruby, powered by llms, designed for simplicity, transp
5
5
  ---
6
6
 
7
7
  [![Twitter Follow](https://img.shields.io/twitter/follow/jxnlco?style=social)](https://twitter.com/jxnlco)
8
+ [![Twitter Follow](https://img.shields.io/twitter/follow/sbayona?style=social)](https://twitter.com/sbayona)
8
9
  [![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://jxnl.github.io/instructor-rb)
9
- [![GitHub issues](https://img.shields.io/github/issues/instructor-ai/instructor-js.svg)](https://github.com/instructor-ai/instructor-rb/issues)
10
+ [![GitHub issues](https://img.shields.io/github/issues/instructor-ai/instructor-rb.svg)](https://github.com/instructor-ai/instructor-rb/issues)
10
11
  [![Discord](https://img.shields.io/discord/1192334452110659664?label=discord)](https://discord.gg/CV8sPM5k5Y)
11
12
 
12
- 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.
13
+ 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!
13
14
 
14
- > ℹ️ **Tip:** Support in other languages
15
+ # Getting Started
15
16
 
16
- Check out ports to other languages below:
17
+ 1. Install Instructor-rb at the command prompt if you haven't yet:
18
+
19
+ ```bash
20
+ $ gem install instructor-rb
21
+ ```
17
22
 
18
- - [Python](https://www.github.com/jxnl/instructor)
19
- - [TS/JS](https://github.com/instructor-ai/instructor-js/)
20
- - [Ruby](https://github.com/instructor-ai/instructor-rb)
21
- - [Elixir](https://github.com/thmsmlr/instructor_ex/)
23
+ 2. In your Ruby project, require the gem:
22
24
 
23
- 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!
25
+ ```ruby
26
+ require 'instructor'
27
+ ```
28
+
29
+ 3. At the beginning of your script, initialize and patch the OpenAI client:
30
+
31
+ ```ruby
32
+ client = Instructor.patch(OpenAI::Client)
33
+ ```
24
34
 
25
35
  ## Usage
26
36
 
@@ -30,7 +40,7 @@ export your OpenAI API key:
30
40
  export OPENAI_API_KEY=sk-...
31
41
  ```
32
42
 
33
- Then use Instructor to extract structured data from text in Ruby:
43
+ 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:
34
44
 
35
45
  ```ruby
36
46
  require 'instructor'
@@ -54,24 +64,33 @@ user = client.chat(
54
64
  response_model: UserDetail
55
65
  )
56
66
 
57
- puts(user.inspect)
58
- {"name"=>"Jason", "age"=>25}
67
+ user.name
68
+ # => "Jason"
69
+ user.age
70
+ # => 25
71
+
59
72
  ```
60
73
 
61
- ## Why use Instructor?
74
+
75
+ > ℹ️ **Tip:** Support in other languages
62
76
 
77
+ Check out ports to other languages below:
63
78
 
64
- 1. **OpenAI Integration** — Integrates seamlessly with OpenAI's API, facilitating efficient data management and manipulation.
79
+ - [Python](https://www.github.com/jxnl/instructor)
80
+ - [TS/JS](https://github.com/instructor-ai/instructor-js/)
81
+ - [Ruby](https://github.com/instructor-ai/instructor-rb)
82
+ - [Elixir](https://github.com/thmsmlr/instructor_ex/)
65
83
 
66
- 2. **Customizable** It offers significant flexibility. Users can tailor validation processes and define unique error messages.
84
+ 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!
85
+
86
+ ## Why use Instructor?
67
87
 
68
- 3. **Widespread Adoption** — As a primary component in Ruby on Rails, it's widely used and backed by a substantial community.
69
88
 
70
- 4. **Tested and Trusted** — Its reliability is proven by extensive real-world application, underscored by its high adoption rate in Ruby-based projects.
89
+ 1. **OpenAI Integration** — Integrates seamlessly with OpenAI's API, facilitating efficient data management and manipulation.
71
90
 
72
- ## More Examples
91
+ 2. **Customizable** — It offers significant flexibility. Users can tailor validation processes and define unique error messages.
73
92
 
74
- If you'd like to see more check out our [cookbook](examples/index.md).
93
+ 3. **Tested and Trusted** Its reliability is proven by extensive real-world application.
75
94
 
76
95
  [Installing Instructor](installation.md) is a breeze.
77
96
 
@@ -0,0 +1,11 @@
1
+ authors:
2
+ jxnl:
3
+ name: Jason Liu
4
+ description: Creator
5
+ avatar: https://avatars.githubusercontent.com/u/4852235?v=4
6
+ url: https://twitter.com/intent/follow?screen_name=jxnlco
7
+ sergiobayona:
8
+ name: Sergio Bayona
9
+ description: Contributor
10
+ avatar: https://avatars.githubusercontent.com/u/155783?v=4
11
+ url: https://twitter.com/intent/follow?screen_name=sergiobayona
@@ -0,0 +1,3 @@
1
+ # Welcome to the Instructor Blog
2
+
3
+ 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.
@@ -0,0 +1,14 @@
1
+ # Patching
2
+
3
+ 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.
4
+
5
+ - `response_model`: Defines the response type for `chat`.
6
+ - `max_retries`: Determines retry attempts for failed `chat` validations.
7
+ - `validation_context`: Provides extra context to the validation process.
8
+
9
+ Instructor-rb only supports the 'tools' mode at the moment. Other modes will be added in the near future.
10
+
11
+ ## Tool Calling
12
+
13
+ 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.
14
+
@@ -0,0 +1,40 @@
1
+ # Philosophy
2
+
3
+ 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.
4
+
5
+ > “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
6
+
7
+ ## The Bridge to Object-Oriented Programming
8
+
9
+ `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.
10
+
11
+ ## The zen of `instructor`
12
+
13
+ Maintain the flexibility and power of Ruby, without unnecessary constraints.
14
+
15
+ 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.
16
+
17
+ 1. Define a Schema
18
+ ```ruby
19
+ class StructuredData
20
+ include EasyTalk::Model
21
+ end
22
+ ```
23
+ 2. Define properties and methods on your schema.
24
+ 3. Encapsulate all your LLM logic into a function `#!ruby def extract(a)`
25
+ 4. Define typed computations against your data with `#!ruby def compute(data: StructuredData)` or call methods on your schema `#!ruby data.compute()`
26
+
27
+ It should be that simple.
28
+
29
+ ## My Goals
30
+
31
+ 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.
32
+
33
+ - The library is a result of my desire for simplicity.
34
+ - The library should help maintain simplicity in your codebase.
35
+ - I won't try to write prompts for you,
36
+ - I don't try to create indirections or abstractions that make it hard to debug in the future
37
+
38
+ 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)
39
+
40
+ Cheers!
@@ -0,0 +1,105 @@
1
+ # EasyTalk Schemas
2
+
3
+ EasyTalk is a Ruby library for describing, generating and validating JSON Schema.
4
+
5
+ ## Basic Usage
6
+
7
+ ```Ruby
8
+
9
+ class UserDetail
10
+ include EasyTalk::Model
11
+
12
+ define_schema do
13
+ property :name, String
14
+ property :age, Integer
15
+ end
16
+ end
17
+ ```
18
+
19
+ ## Descriptions are Prompts
20
+
21
+ One of the core things about instructors is that it's able to use these descriptions as part of the prompt.
22
+
23
+ ```Ruby
24
+ class UserDetail
25
+ include EasyTalk::Model
26
+
27
+ define_schema do
28
+ description 'Fully extracted user detail'
29
+ property :name, String, description: 'Your full name'
30
+ property :age, Integer
31
+ end
32
+ end
33
+ ```
34
+
35
+ ## Model Composition
36
+
37
+ EasyTalk models can themselves be composed of other models.
38
+
39
+ ```Ruby
40
+ class Address
41
+ include EasyTalk::Model
42
+
43
+ define_schema do
44
+ property :street, String
45
+ property :city, String
46
+ end
47
+ end
48
+
49
+ class UserDetail
50
+ include EasyTalk::Model
51
+
52
+ define_schema do
53
+ property :name, String
54
+ property :address, Address
55
+ end
56
+ end
57
+
58
+ ```
59
+
60
+ ## Default Values
61
+
62
+ In order to help the language model, we can also define defaults for the values.
63
+
64
+ ```Ruby
65
+ class UserDetail
66
+ include EasyTalk::Model
67
+
68
+ define_schema do
69
+ property :name, String
70
+ property :is_student, Boolean, default: false
71
+ end
72
+ end
73
+
74
+ ```
75
+ ## Arrays
76
+
77
+ Arrays can be defined using the `T::Array[]` method.
78
+
79
+ ```Ruby
80
+ class UserDetail
81
+ include EasyTalk::Model
82
+
83
+ define_schema do
84
+ property :name, String
85
+ property :friends, T::Array[String]
86
+ end
87
+ end
88
+
89
+ ```
90
+
91
+ ## Enums
92
+
93
+ Enums can be defined using the `enum` constraint.
94
+
95
+ ```Ruby
96
+ class UserDetail
97
+ include EasyTalk::Model
98
+
99
+ define_schema do
100
+ property :name, String
101
+ property :role, String, enum: %w[admin user]
102
+ end
103
+ end
104
+
105
+ ```
@@ -0,0 +1,90 @@
1
+ We would love for you to contribute to `Instructor-rb`.
2
+
3
+ ## Migrating Docs from Python
4
+
5
+ Theres a bunch of examples in the python version, including documentation here [python docs](https://jxnl.github.io/instructor/examples/)
6
+
7
+ If you want to contribute, please check out [issues](https://github.com/instructor-ai/instructor/issues)
8
+
9
+ ## Issues
10
+
11
+ If you find a bug, please file an issue on [our issue tracker on GitHub](https://github.com/instructor-ai/instructor-rb/issues).
12
+
13
+ To help us reproduce the bug, please provide a minimal reproducible example, including a code snippet and the full error message as well as:
14
+
15
+ 1. The `response_model` you are using.
16
+ 2. The `messages` you are using.
17
+ 3. The `model` you are using.
18
+
19
+ ---
20
+
21
+ ## Environment Setup
22
+
23
+ Ruby 3.2.1 is required to run the project.
24
+
25
+
26
+ ### Installation
27
+
28
+ 1. **Install Dependencies**:
29
+ Run the following command to install the project dependencies:
30
+
31
+ ```bash
32
+ bundle install
33
+ ```
34
+
35
+ 2. **Environment Variables**:
36
+ setup the OpenAI API key in your environment variables.
37
+
38
+ ```bash
39
+
40
+ ### Code Quality Tools
41
+
42
+ - This project uses rubocop.
43
+
44
+ ### Running Tests
45
+
46
+ - Execute tests using the following command:
47
+
48
+ ```bash
49
+ bundle exec rspec
50
+ ```
51
+
52
+ ### Running the Rubocop
53
+
54
+ ```bash
55
+ bundle exec rubocop
56
+ ```
57
+
58
+ ### Pull Requests
59
+
60
+ We welcome pull requests! There is plenty to do, and we are happy to discuss any contributions you would like to make.
61
+
62
+ If it is not a small change, please start by [filing an issue](https://github.com/instructor-ai/instructor-rb/issues) first.
63
+
64
+
65
+ ## Community and Support
66
+
67
+ - Join our community on Discord: [Join Discord](https://discord.gg/DWHZdqpNgz)
68
+ - Reach out on Twitter: [@sergiobayona](https://twitter.com/sergiobayona) [@jxnlco](https://twitter.com/jxnlco)
69
+
70
+ ## Contributors
71
+
72
+ <a href="https://github.com/jxnl/instructor/graphs/contributors">
73
+ <img src="https://contrib.rocks/image?repo=instructor-ai/instructor-rb" />
74
+ </a>
75
+
76
+
77
+ ## Additional Resources
78
+ Python is required to run the documentation locally using mkdocs.
79
+
80
+ To improve your understanding of the documentation, here are some useful references:
81
+
82
+ - **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/).
83
+
84
+ - **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).
85
+
86
+ - **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).
87
+
88
+ For more details about the documentation structure and features, refer to the [MkDocs Material documentation](https://squidfunk.github.io/mkdocs-material/).
89
+
90
+ Thank you for your contributions, and happy coding!
@@ -0,0 +1,163 @@
1
+ # Example: Extracting Action Items from Meeting Transcripts
2
+
3
+ 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.
4
+
5
+ !!! tips "Motivation"
6
+
7
+ 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.
8
+
9
+ ## Defining the Structures
10
+
11
+ 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.
12
+
13
+ ```Ruby
14
+ class Subtask
15
+ include EasyTalk::Model
16
+
17
+ define_schema do
18
+ property :id, Integer, description: 'Unique identifier for the subtask'
19
+ property :name, String, description: 'Informative title of the subtask'
20
+ end
21
+ end
22
+
23
+ class Ticket
24
+ include EasyTalk::Model
25
+
26
+ PRIORITY = %w[low medium high].freeze
27
+
28
+ define_schema do
29
+ property :id, Integer, description: 'Unique identifier for the ticket'
30
+ property :name, String, description: 'Title of the ticket'
31
+ property :description, String, description: 'Detailed description of the ticket'
32
+ property :priority, String, description: 'Priority level'
33
+ property :assignees, T::Array[String], description: 'List of users assigned to the ticket'
34
+ property :subtasks, T.nilable(T::Array[Subtask]), description: 'List of subtasks associated with the ticket'
35
+ property :dependencies, T.nilable(T::Array[Integer]),
36
+ description: 'List of ticket IDs that this ticket depends on'
37
+ end
38
+ end
39
+
40
+ class ActionItems
41
+ include EasyTalk::Model
42
+
43
+ define_schema do
44
+ property :items, T::Array[Ticket]
45
+ end
46
+ end
47
+ ```
48
+
49
+ ## Extracting Action Items
50
+
51
+ 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`**.
52
+
53
+ ```Ruby
54
+
55
+ def extract_action_items(data)
56
+ client = Instructor.patch(OpenAI::Client).new
57
+
58
+ client.chat(
59
+ parameters: {
60
+ model: 'gpt-3.5-turbo',
61
+ messages: [
62
+ {
63
+ role: 'system',
64
+ "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.'
65
+ },
66
+ {
67
+ "role": 'user',
68
+ "content": "Create the action items for the following transcript: #{data}"
69
+ }
70
+ ]
71
+ },
72
+ response_model: ActionItems
73
+ )
74
+ end
75
+ ```
76
+
77
+ ## Evaluation and Testing
78
+
79
+ 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.
80
+
81
+ ```Ruby
82
+ data = <<~DATA
83
+ 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.
84
+
85
+ Bob: Got it, Alice. I can take the lead on the authentication improvements. Are there any specific areas you want me to focus on?
86
+
87
+ Alice: Good question, Bob. We need both a front-end revamp and back-end optimization. So basically, two sub-tasks.
88
+
89
+ Carol: I can help with the front-end part of the authentication system.
90
+
91
+ Bob: Great, Carol. I'll handle the back-end optimization then.
92
+
93
+ 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.
94
+
95
+ Carol: Is the new billing system already in place?
96
+
97
+ Alice: No, it's actually another task. So it's a dependency for the integration task. Bob, can you also handle the billing system?
98
+
99
+ Bob: Sure, but I'll need to complete the back-end optimization of the authentication system first, so it's dependent on that.
100
+
101
+ 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.
102
+
103
+ Carol: I can take that on once the front-end changes for the authentication system are done. So, it would be dependent on that.
104
+
105
+ Alice: Sounds like a plan. Let's get these tasks modeled out and get started.
106
+ DATA
107
+
108
+ result = generate(data)
109
+ puts(result.as_json)
110
+ ```
111
+
112
+ ## Visualizing the tasks
113
+
114
+ In order to quickly visualize the data we used code interpreter to create a graphviz export of the json version of the ActionItems array.
115
+
116
+ ![action items](action_items.png)
117
+
118
+ ```json
119
+ {
120
+ "items": [
121
+ {
122
+ "id": 1,
123
+ "name": "Improve Authentication System",
124
+ "description": "Revamp the front-end and optimize the back-end of the authentication system",
125
+ "priority": "High",
126
+ "assignees": ["Bob", "Carol"],
127
+ "subtasks": [
128
+ {
129
+ "id": 2,
130
+ "name": "Front-end Revamp"
131
+ },
132
+ {
133
+ "id": 3,
134
+ "name": "Back-end Optimization"
135
+ }
136
+ ],
137
+ "dependencies": []
138
+ },
139
+ {
140
+ "id": 4,
141
+ "name": "Integrate Authentication System with Billing System",
142
+ "description": "Integrate the improved authentication system with the new billing system",
143
+ "priority": "Medium",
144
+ "assignees": ["Bob"],
145
+ "subtasks": [],
146
+ "dependencies": [1]
147
+ },
148
+ {
149
+ "id": 5,
150
+ "name": "Update User Documentation",
151
+ "description": "Update the user documentation to reflect the changes in the authentication system",
152
+ "priority": "Low",
153
+ "assignees": ["Carol"],
154
+ "subtasks": [],
155
+ "dependencies": [2]
156
+ }
157
+ ]
158
+ }
159
+ ```
160
+
161
+ 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.
162
+
163
+ 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.
Binary file
@@ -0,0 +1,2 @@
1
+ # Classification
2
+ Pending update
@@ -0,0 +1,2 @@
1
+ # Content Moderation
2
+ pending update
@@ -0,0 +1,18 @@
1
+ # Cookbook
2
+
3
+ !!! warning "Page under construction"
4
+
5
+ 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/)
6
+
7
+ If you want to contribute, please check out [issues](https://github.com/instructor-ai/instructor-js/issues/8)
8
+
9
+
10
+
11
+ ## Table of Contents
12
+
13
+ - [How do I do classification?](./classification.md)
14
+ - [How are complex queries decomposed into subqueries for a single request?](./query_decomposition.md)
15
+ - [How are action items and dependencies generated from transcripts?](./action_items.md)
16
+ - [How is AI self-assessment implemented with llm_validator?](./self_correction.md)
17
+ - [How are exact citations retrieved using regular expressions and smart prompting?](./validated_citations.md)
18
+ - [How to enable OpenAI's moderation](./content_moderation.md)
@@ -0,0 +1,2 @@
1
+ # Query Decomposition
2
+ Pending update
@@ -0,0 +1,2 @@
1
+ # Self Correction
2
+ Pending update
@@ -0,0 +1,2 @@
1
+ # Validated Citations
2
+ Pending update
data/docs/help.md ADDED
@@ -0,0 +1,32 @@
1
+ !!! warning "Page under construction"
2
+
3
+ This page is under construction. Please check back later. Consider contributing to this page by opening a PR!
4
+
5
+
6
+ # Getting help with Instructor
7
+
8
+ If you need help getting started with Instructor or with advanced usage, the following sources may be useful.
9
+
10
+ ## :fontawesome-brands-discord: Discord
11
+
12
+ 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.
13
+
14
+ ## :material-creation: Concepts
15
+
16
+ The [concepts](concepts/prompting.md) section explains the core concepts of Instructor and how to prompt with models.
17
+
18
+ ## :material-chef-hat: Cookbooks
19
+
20
+ 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.
21
+
22
+ ## :material-github: GitHub Discussions
23
+
24
+ [GitHub discussions](https://github.com/instructor-ai/instructor-rb/discussions) are useful for asking questions, your question and the answer will help everyone.
25
+
26
+ ## :material-github: GitHub Issues
27
+
28
+ [GitHub issues](https://github.com/instructor-ai/instructor-rb/issues) are useful for reporting bugs or requesting new features.
29
+
30
+ ## :material-twitter: Twitter
31
+
32
+ You can also reach out to me on [Twitter](https://twitter.com/jxnlco) if you have any questions or ideas.
data/docs/index.md ADDED
@@ -0,0 +1,76 @@
1
+ # instructor-rb
2
+
3
+ _Structured extraction in Ruby, powered by llms, designed for simplicity, transparency, and control._
4
+
5
+ ---
6
+
7
+ [![Twitter Follow](https://img.shields.io/twitter/follow/jxnlco?style=social)](https://twitter.com/jxnlco)
8
+ [![Twitter Follow](https://img.shields.io/twitter/follow/sergiobayona?style=social)](https://twitter.com/sergiobayona)
9
+ [![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://jxnl.github.io/instructor-rb)
10
+ [![GitHub issues](https://img.shields.io/github/issues/instructor-ai/instructor-js.svg)](https://github.com/instructor-ai/instructor-rb/issues)
11
+ [![Discord](https://img.shields.io/discord/1192334452110659664?label=discord)](https://discord.gg/DWHZdqpNgz)
12
+
13
+ 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.
14
+
15
+ 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).
16
+
17
+ 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!
18
+
19
+ ## Usage
20
+
21
+ 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/).
22
+
23
+ ```Ruby
24
+ require 'instructor-rb'
25
+
26
+ OpenAI.configure do |config|
27
+ config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
28
+ config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional.
29
+ end
30
+
31
+ class UserDetail
32
+ include EasyTalk::Model
33
+
34
+ define_schema do
35
+ property :name, String
36
+ property :age, Integer
37
+ end
38
+ end
39
+
40
+ client = Instructor.patch(OpenAI::Client).new
41
+
42
+ user = client.chat(
43
+ parameters: {
44
+ model: 'gpt-3.5-turbo',
45
+ messages: [{ role: 'user', content: 'Extract Jason is 25 years old' }]
46
+ },
47
+ response_model: UserDetail
48
+ )
49
+
50
+ user.name
51
+ # => "Jason"
52
+ user.age
53
+ # => 25
54
+ ```
55
+
56
+ ## Why use Instructor?
57
+
58
+ The question of using Instructor is fundamentally a question of why to use zod.
59
+
60
+ 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.
61
+
62
+ 2. **Ruby Schema Validation** — Instructor uses Ruby schema validation with type hinting. This means you can validate your data before using it.
63
+
64
+ ## More Examples
65
+
66
+ If you'd like to see more check out our [cookbook](examples/index.md).
67
+
68
+ [Installing Instructor](installation.md) is a breeze.
69
+
70
+ ## Contributing
71
+
72
+ 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.
73
+
74
+ ## License
75
+
76
+ This project is licensed under the terms of the MIT License.
@@ -0,0 +1,5 @@
1
+ Installation is as simple as:
2
+
3
+ ```bash
4
+ gem install intructor-rb
5
+ ```
@@ -0,0 +1,31 @@
1
+ {% extends "base.html" %}
2
+ <script>
3
+ !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||[]);
4
+ posthog.init('phc_bAUjZfg1PI0Ca2IOQCM053Y5873PRZhJ0DvTDbGsN9A',{api_host:'https://p.useinstructor.com'})
5
+ </script>
6
+
7
+ {% block announce %} For updates follow
8
+ <strong>@jxnlco</strong> on
9
+ <a href="https://twitter.com/jxnlco">
10
+ <span class="twemoji twitter">
11
+ {% include ".icons/fontawesome/brands/twitter.svg" %}
12
+ </span>
13
+ <strong>Twitter</strong>
14
+ </a>
15
+ and
16
+ <span class="twemoji star">
17
+ {% include ".icons/fontawesome/solid/star.svg" %}
18
+ </span>
19
+ us on
20
+ <a href="https://www.github.com/instructor-ai/instructor-rb">
21
+ <span class="twemoji github">
22
+ {% include ".icons/fontawesome/brands/github.svg" %}
23
+ </span>
24
+ <strong>GitHub</strong> </a
25
+ >. If you don't like Ruby, check out the
26
+ <a href="https://www.github.com/jxnl/instructor"><strong>Python</strong></a>,
27
+ <a href="https://github.com/thmsmlr/instructor_ex/">
28
+ <strong>Elixir</strong>
29
+ </a> and
30
+ <a href="https://github.com/instructor-ai/instructor-js"><strong>JavaScript</strong></a>
31
+ ports. {% endblock %}
@@ -118,19 +118,29 @@ module Instructor
118
118
  {
119
119
  type: 'function',
120
120
  function: {
121
- name: model.name.humanize.titleize,
121
+ name: generate_function_name(model),
122
122
  description: generate_description(model),
123
123
  parameters: model.json_schema
124
124
  }
125
125
  }
126
126
  end
127
127
 
128
+ def generate_function_name(model)
129
+ model.schema.fetch(:title, model.name)
130
+ end
131
+
128
132
  # Generates the description for the function.
129
133
  #
130
134
  # @param model [Class] The response model class.
131
135
  # @return [String] The generated description.
132
136
  def generate_description(model)
133
- "Correctly extracted `#{model.name}` with all the required parameters with correct types"
137
+ if model.respond_to?(:instructions)
138
+ raise Instructor::Error, 'The instructions must be a string' unless model.instructions.is_a?(String)
139
+
140
+ model.instructions
141
+ else
142
+ "Correctly extracted `#{model.name}` with all the required parameters with correct types"
143
+ end
134
144
  end
135
145
 
136
146
  # Checks if the response is iterable.
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Instructor
4
- VERSION = '0.1.0'
4
+ VERSION = '0.1.2'
5
5
  end
data/mkdocs.yml ADDED
@@ -0,0 +1,191 @@
1
+ site_name: Instructor (Ruby)
2
+ site_author: Jason Liu
3
+ site_description: Structured LLM outputs with EasyTalk
4
+ repo_name: instructor
5
+ repo_url: https://github.com/instructor-ai/instructor-rb
6
+ site_url: https://ruby.useinstructor.com/
7
+ edit_uri: edit/main/docs/
8
+ copyright: Copyright &copy; 2024 Jason Liu
9
+ theme:
10
+ name: material
11
+ icon:
12
+ repo: fontawesome/brands/github
13
+ edit: material/pencil
14
+ view: material/eye
15
+ theme:
16
+ admonition:
17
+ note: octicons/tag-16
18
+ abstract: octicons/checklist-16
19
+ info: octicons/info-16
20
+ tip: octicons/squirrel-16
21
+ success: octicons/check-16
22
+ question: octicons/question-16
23
+ warning: octicons/alert-16
24
+ failure: octicons/x-circle-16
25
+ danger: octicons/zap-16
26
+ bug: octicons/bug-16
27
+ example: octicons/beaker-16
28
+ quote: octicons/quote-16
29
+ features:
30
+ - announce.dismiss
31
+ - content.action.edit
32
+ - content.action.view
33
+ - content.code.annotate
34
+ - content.code.copy
35
+ - content.code.select
36
+ - content.tabs.link
37
+ - content.tooltips
38
+ - header.autohide
39
+ - navigation.expand
40
+ - navigation.footer
41
+ - navigation.indexes
42
+ - navigation.instant
43
+ - navigation.instant.prefetch
44
+ - navigation.instant.progress
45
+ - navigation.prune
46
+ - navigation.sections
47
+ - navigation.tabs
48
+ # - navigation.tabs.sticky
49
+ - navigation.top
50
+ - navigation.tracking
51
+ - search.highlight
52
+ - search.share
53
+ - search.suggest
54
+ - toc.follow
55
+ # - toc.integrate
56
+ palette:
57
+ - scheme: default
58
+ primary: black
59
+ accent: indigo
60
+ toggle:
61
+ icon: material/brightness-7
62
+ name: Switch to dark mode
63
+ - scheme: slate
64
+ primary: black
65
+ accent: indigo
66
+ toggle:
67
+ icon: material/brightness-4
68
+ name: Switch to light mode
69
+ font:
70
+ text: Roboto
71
+ code: Roboto Mono
72
+ custom_dir: docs/overrides
73
+ # Extensions
74
+ markdown_extensions:
75
+ - abbr
76
+ - admonition
77
+ - pymdownx.details
78
+ - attr_list
79
+ - def_list
80
+ - footnotes
81
+ - md_in_html
82
+ - toc:
83
+ permalink: true
84
+ - pymdownx.arithmatex:
85
+ generic: true
86
+ - pymdownx.betterem:
87
+ smart_enable: all
88
+ - pymdownx.caret
89
+ - pymdownx.details
90
+ - pymdownx.emoji:
91
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
92
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
93
+ - pymdownx.highlight:
94
+ anchor_linenums: true
95
+ line_spans: __span
96
+ pygments_lang_class: true
97
+ - pymdownx.inlinehilite
98
+ - pymdownx.keys
99
+ - pymdownx.magiclink:
100
+ normalize_issue_symbols: true
101
+ repo_url_shorthand: true
102
+ user: jxnl
103
+ repo: instructor
104
+ - pymdownx.mark
105
+ - pymdownx.smartsymbols
106
+ - pymdownx.snippets:
107
+ auto_append:
108
+ - includes/mkdocs.md
109
+ - pymdownx.superfences:
110
+ custom_fences:
111
+ - name: mermaid
112
+ class: mermaid
113
+ format: !!python/name:pymdownx.superfences.fence_code_format
114
+ - pymdownx.tabbed:
115
+ alternate_style: true
116
+ combine_header_slug: true
117
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
118
+ kwds:
119
+ case: lower
120
+ - pymdownx.tasklist:
121
+ custom_checkbox: true
122
+ - pymdownx.tilde
123
+ nav:
124
+ - Introduction:
125
+ - Welcome To Instructor: 'index.md'
126
+ - Why use Instructor?: 'why.md'
127
+ - Schema: 'concepts/schema.md'
128
+ - Patching: 'concepts/patching.md'
129
+ - Streaming: 'concepts/streaming.md'
130
+ - Logging: 'concepts/logging.md'
131
+ - Prompting Tips: 'tips/prompting.md'
132
+ - Philosophy: 'concepts/philosophy.md'
133
+ - Help with Instructor: 'help.md'
134
+ - Installation: 'installation.md'
135
+ - Contributing: 'contributing.md'
136
+ - Cookbook:
137
+ - Overview: 'examples/index.md'
138
+ - Classification: 'examples/classification.md'
139
+ - Query Decomposition: 'examples/query_decomposition.md'
140
+ - Action Item and Dependency Mapping: 'examples/action_items.md'
141
+ - Self Correction: 'examples/self_correction.md'
142
+ - Citing Sources: 'examples/validated_citations.md'
143
+ - Content Moderation: 'examples/content_moderation.md'
144
+ - Blog:
145
+ - "blog/index.md"
146
+
147
+ plugins:
148
+ - social
149
+ - search:
150
+ separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
151
+ - minify:
152
+ minify_html: true
153
+ - mkdocstrings:
154
+ handlers:
155
+ python:
156
+ options:
157
+ members_order: alphabetical
158
+ allow_inspection: true
159
+ show_bases: true
160
+ - blog:
161
+ enabled: !ENV CI
162
+ blog_dir: "blog"
163
+ blog_toc: true
164
+ post_dir: blog/posts
165
+ post_date_format: yyyy/MM/dd
166
+ post_url_format: "{date}/{slug}"
167
+ authors_file: "{blog}/.authors.yml"
168
+ extra:
169
+ analytics:
170
+ provider: google
171
+ property: G-3JFF533YVZ
172
+ feedback:
173
+ title: Was this page helpful?
174
+ ratings:
175
+ - icon: material/emoticon-happy-outline
176
+ name: This page was helpful
177
+ data: 1
178
+ note: >-
179
+ Thanks for your feedback!
180
+ - icon: material/emoticon-sad-outline
181
+ name: This page could be improved
182
+ data: 0
183
+ note: >-
184
+ Thanks for your feedback! Help us improve this page by
185
+ using our <a href="..." target="_blank" rel="noopener">feedback form</a>.
186
+ social:
187
+ - icon: fontawesome/brands/twitter
188
+ link: https://twitter.com/jxnlco
189
+ - icon: fontawesome/brands/github
190
+ link: https://github.com/jxnl
191
+ copyright: Copyright &copy; 2024 Jason Liu
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: instructor-rb
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Sergio Bayona
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2024-04-24 00:00:00.000000000 Z
12
+ date: 2024-05-17 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: activesupport
@@ -31,14 +31,14 @@ dependencies:
31
31
  requirements:
32
32
  - - "~>"
33
33
  - !ruby/object:Gem::Version
34
- version: 0.1.8
34
+ version: '0.2'
35
35
  type: :runtime
36
36
  prerelease: false
37
37
  version_requirements: !ruby/object:Gem::Requirement
38
38
  requirements:
39
39
  - - "~>"
40
40
  - !ruby/object:Gem::Version
41
- version: 0.1.8
41
+ version: '0.2'
42
42
  - !ruby/object:Gem::Dependency
43
43
  name: ruby-openai
44
44
  requirement: !ruby/object:Gem::Requirement
@@ -189,16 +189,36 @@ extensions: []
189
189
  extra_rdoc_files: []
190
190
  files:
191
191
  - ".rubocop.yml"
192
+ - CHANGELOG.md
192
193
  - LICENSE
193
194
  - README.md
194
195
  - Rakefile
195
196
  - bin/console
197
+ - docs/blog/.authors.yml
198
+ - docs/blog/index.md
199
+ - docs/concepts/patching.md
200
+ - docs/concepts/philosophy.md
201
+ - docs/concepts/schema.md
202
+ - docs/contributing.md
203
+ - docs/examples/action_items.md
204
+ - docs/examples/action_items.png
205
+ - docs/examples/classification.md
206
+ - docs/examples/content_moderation.md
207
+ - docs/examples/index.md
208
+ - docs/examples/query_decomposition.md
209
+ - docs/examples/self_correction.md
210
+ - docs/examples/validated_citations.md
211
+ - docs/help.md
212
+ - docs/index.md
213
+ - docs/installation.md
214
+ - docs/overrides/main.html
196
215
  - ellipsis.Dockerfile
197
216
  - ellipsis.yaml
198
217
  - lib/instructor.rb
199
218
  - lib/instructor/openai/patch.rb
200
219
  - lib/instructor/openai/response.rb
201
220
  - lib/instructor/version.rb
221
+ - mkdocs.yml
202
222
  homepage: https://github.com/instructor-ai/instructor-rb
203
223
  licenses:
204
224
  - MIT