feat(Instructor): introduce Instructor Hub with tutorials, examples, and new CLI

docs/hub/index.md

@@ -0,0 +1,63 @@
+# Instructor Hub
+
+Welcome to instructor hub, the goal of this project is to provide a set of tutorials and examples to help you get started, and allow you to pull in the code you need to get started with `instructor`
+
+## Contributing
+
+We welcome contributions to the instructor hub, if you have a tutorial or example you'd like to add, please open a pull request in `docs/hub` and we'll review it.
+
+1. The code must be in a single file
+2. Make sure that its referenced in the `mkdocs.yml`
+3. Make sure that the code is unit tested.
+
+### Using pytest_examples
+
+By running the following command you can run the tests and update the examples. This ensures that the examples are always up to date.
+Linted correctly and that the examples are working, make sure to include a `if __name__ == "__main__":` block in your code and add some asserts to ensure that the code is working.
+
+```bash
+poetry run pytest tests/openai/docs/test_hub.py --update-examples
+```
+
+## Command Line Interface
+
+Instructor hub comes with a command line interface (CLI) that allows you to view and interact with the tutorials and examples and allows you to pull in the code you need to get started with the API.
+
+### Listing Available Cookbooks
+
+By running `instructor hub list` you can see all the available tutorials and examples. By clickony (doc) you can see the full tutorial back on this website.
+
+```bash
+$ instructor hub list
+                         Available Cookbooks
+┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ hub_id ┃ slug                        ┃ title                       ┃
+┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│      1 │ single_classification (doc) │ Single Classification Model │
+└────────┴─────────────────────────────┴─────────────────────────────┘
+```
+
+### Viewing a Tutorial
+
+To read a tutorial, you can run `instructor hub show --id <hub_id> --page` to see the full tutorial in the terminal. You can use `j,k` to scroll up and down, and `q` to quit. You can also run it without `--page` to print the tutorial to the terminal.
+
+```bash
+$ instructor hub show --id 1 --page
+```
+
+### Pulling in Code
+
+To pull in the code for a tutorial, you can run `instructor hub pull --id <hub_id> --py`. This will print the code to the terminal, then you can `|` pipe it to a file to save it.
+
+```bash
+$ instructor hub pull --id 1 --py > classification.py
+```
+
+## Future Work
+
+This is a experimental in the future we'd like to have some more features like:
+
+- [ ] Options for async/sync code
+- [ ] Options for connecting with langsmith
+- [ ] Standard directory structure for the code
+- [ ] Options for different languages

docs/hub/single_classification.md

@@ -0,0 +1,47 @@
+# Single-Label Classification
+
+This example demonstrates how to perform single-label classification using the OpenAI API. The example uses the `gpt-3.5-turbo` model to classify text as either `SPAM` or `NOT_SPAM`.
+
+```python
+from pydantic import BaseModel, Field
+from typing import Literal
+from openai import OpenAI
+import instructor
+
+# Apply the patch to the OpenAI client
+# enables response_model keyword
+client = instructor.patch(OpenAI())
+
+
+class ClassificationResponse(BaseModel):
+    label: Literal["SPAM", "NOT_SPAM"] = Field(
+        ...,
+        description="The predicted class label.",
+    )
+
+
+def classify(data: str) -> ClassificationResponse:
+    """Perform single-label classification on the input text."""
+    return client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        response_model=ClassificationResponse,
+        messages=[
+            {
+                "role": "user",
+                "content": f"Classify the following text: {data}",
+            },
+        ],
+    )
+
+
+if __name__ == "__main__":
+    for text, label in [
+        ("Hey Jason! You're awesome", "NOT_SPAM"),
+        ("I am a nigerian prince and I need your help.", "SPAM"),
+    ]:
+        prediction = classify(text)
+        assert prediction.label == label
+        print(f"Text: {text}, Predicted Label: {prediction.label}")
+        #> Text: Hey Jason! You're awesome, Predicted Label: NOT_SPAM
+        #> Text: I am a nigerian prince and I need your help., Predicted Label: SPAM
+```

instructor/cli/cli.py

@@ -2,6 +2,7 @@
 import instructor.cli.jobs as jobs
 import instructor.cli.files as files
 import instructor.cli.usage as usage
+import instructor.cli.hub as hub
 
 app = typer.Typer(
     name="instructor-ft",
@@ -11,3 +12,4 @@
 app.add_typer(jobs.app, name="jobs", help="Monitor and create fine tuning jobs")
 app.add_typer(files.app, name="files", help="Manage files on OpenAI's servers")
 app.add_typer(usage.app, name="usage", help="Check OpenAI API usage data")
+app.add_typer(hub.app, name="hub", help="Interact with the instructor hub")

instructor/cli/hub.py

@@ -0,0 +1,157 @@
+from typing import Iterable, Optional
+
+import typer
+import httpx
+import yaml
+
+from rich.console import Console
+from rich.table import Table
+from rich.markdown import Markdown
+
+app = typer.Typer(
+    name="hub",
+    help="Interact with the instructor hub, a collection of examples and cookbooks for the instructor library.",
+    short_help="Interact with the instructor hub",
+)
+console = Console()
+
+
+class HubPage(BaseModel):
+    id: int
+    branch: str = "main"
+    slug: str
+    title: str
+
+    def get_doc_url(self):
+        """
+        Returns the URL for the documentation
+        """
+        return f"https://jxnl.github.io/instructor/hub/{self.slug}/"
+
+    def get_md_url(self):
+        """
+        Returns the raw URL for the markdown file
+        """
+        return f"https://raw.githubusercontent.com/jxnl/instructor/{self.branch}/docs/hub/{self.slug}.md?raw=true"
+
+    def render_doc_link(self):
+        """
+        Rich Render the documentation link
+        """
+        return f"[link={self.get_doc_url()}](doc)[/link]"
+
+    def render_slug(self):
+        """
+        Rich Render the slug with a clickable link to the documentation
+        """
+        return f"{self.slug} {self.render_doc_link()}"
+
+    def get_md(self):
+        url = self.get_md_url()
+        resp = httpx.get(url)
+        return resp.content.decode("utf-8")
+
+    def get_py(self):
+        import re
+
+        url = self.get_md_url()
+        resp = httpx.get(url)
+        script_str = resp.content.decode("utf-8")
+
+        code_blocks = re.findall(r"```(python|py)(.*?)```", script_str, re.DOTALL)
+        code = "\n".join([code_block for (_, code_block) in code_blocks])
+        return code
+
+
+def mkdoc_yaml_url(branch="main") -> str:
+    return f"https://raw.githubusercontent.com/jxnl/instructor/{branch}/mkdocs.yml?raw=true"
+
+
+def list_hub(branch="main") -> Iterable[HubPage]:
+    resp = httpx.get(mkdoc_yaml_url(branch))
+    mkdocs_config = resp.content.decode("utf-8").replace("!", "")
+    data = yaml.safe_load(mkdocs_config)
+
+    # Replace with Hub key
+    cookbooks = [obj["Hub"] for obj in data.get("nav", []) if "Hub" in obj][0]
+    for id, cookbook in enumerate(cookbooks):
+        title, link = list(cookbook.items())[0]
+        slug = link.split("/")[-1].replace(".md", "")
+        if slug != "index":
+            yield HubPage(id=id, branch=branch, slug=slug, title=title)
+
+
+def get_cookbook_by_id(id: int, branch="main"):
+    for cookbook in list_hub(branch):
+        if cookbook.id == id:
+            return cookbook
+    return None
+
+
+def get_cookbook_by_slug(slug: str, branch="main"):
+    for cookbook in list_hub(branch):
+        if cookbook.slug == slug:
+            return cookbook
+    return None
+
+
+@app.command(
+    "list",
+    help="List all available cookbooks",
+    short_help="List all available cookbooks",
+)
+def list_cookbooks(
+    branch: str = typer.Option(
+        "hub",
+        "--branch",
+        "-b",
+        help="Specific branch to fetch the cookbooks from. Defaults to 'main'.",
+    ),
+):
+    table = Table(title="Available Cookbooks")
+    table.add_column("hub_id", justify="right", style="cyan", no_wrap=True)
+    table.add_column("slug", style="green")
+    table.add_column("title", style="white")
+
+    for cookbook in list_hub(branch):
+        ii = cookbook.id
+        slug = cookbook.render_slug()
+        title = cookbook.title
+        table.add_row(str(ii), slug, title)
+
+    console.print(table)
+
+
+@app.command(
+    "pull",
+    help="Pull the latest cookbooks from the instructor hub, optionally outputting to a file",
+    short_help="Pull the latest cookbooks",
+)
+def pull(
+    id: Optional[int] = typer.Option(None, "--id", "-i", help="The cookbook id"),
+    slug: Optional[str] = typer.Option(None, "--slug", "-s", help="The cookbook slug"),
+    py: bool = typer.Option(False, "--py", help="Output to a Python file"),
+    branch: str = typer.Option(
+        "hub", help="Specific branch to fetch the cookbooks from."
+    ),
+    page: bool = typer.Option(
+        False, "--page", "-p", help="Paginate the output with a less-like pager"
+    ),
+):
+    cookbook = (
+        get_cookbook_by_id(id, branch)
+        if id
+        else get_cookbook_by_slug(slug, branch)
+        if slug
+        else None
+    )
+    if not cookbook:
+        typer.echo("Please provide a valid cookbook id or slug.")
+        raise typer.Exit(code=1)
+
+    output = cookbook.get_py() if py else Markdown(cookbook.get_md())
+    if page:
+        with console.pager(styles=True):
+            console.print(output)
+    else:
+        console.print(output)

mkdocs.yml

@@ -114,7 +114,6 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
       combine_header_slug: true
-      slugify: !!python/object/apply:pymdownx.slugs.slugify
   - pymdownx.tasklist:
       custom_checkbox: true
 nav:
@@ -164,6 +163,9 @@ nav:
     - Image to Ad Copy: 'examples/image_to_ad_copy.md'
     - Ollama: 'examples/ollama.md'
     - SQLModel Integration: 'examples/sqlmodel.md'
+  - Hub:
+    - Introduction: 'hub/index.md'
+    - Single Classification Model: 'hub/single_classification.md'
   - Tutorials:
     - Introduction: 'tutorials/1-introduction.ipynb'
     - Tips and Tricks: 'tutorials/2-tips.ipynb'

tests/openai/docs/test_hub.py

@@ -0,0 +1,12 @@
+import pytest
+from pytest_examples import find_examples, CodeExample, EvalExample
+
+
+@pytest.mark.parametrize("example", find_examples("docs/hub"), ids=str)
+def test_format_blog(example: CodeExample, eval_example: EvalExample):
+    if eval_example.update_examples:
+        eval_example.format(example)
+        eval_example.run_print_update(example)
+    else:
+        eval_example.lint(example)
+        eval_example.run(example)