Skip to content

Commit

Permalink
updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@sergiobayona
sergiobayona committed May 7, 2024
1 parent b6b5e57 commit 9d5b298
Show file tree
Hide file tree
Showing 6 changed files with 64 additions and 308 deletions.
72 changes: 20 additions & 52 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,115 +1,83 @@
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.
3. The `model` you are using.

---

# 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

1. **Install Dependencies**:
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

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

<a href="https://github.com/jxnl/instructor/graphs/contributors">
<img src="https://contrib.rocks/image?repo=instructor-ai/instructor-js" />
<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 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/).

Expand Down
67 changes: 0 additions & 67 deletions docs/guidelines.md
View file

This file was deleted.

6 changes: 3 additions & 3 deletions docs/help.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
87 changes: 40 additions & 47 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<typeof UserSchema>
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?
Expand All @@ -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

Expand Down
8 changes: 1 addition & 7 deletions docs/installation.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Loading

0 comments on commit 9d5b298

Please sign in to comment.