mirrors/567-labs--instructor
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
Ruff / Ruff (push) Has been cancelled
Details
Test / Core Tests (push) Has been cancelled
Details
Test / Offline Coverage Tests (Python 3.10) (push) Has been cancelled
Details
Test / Offline Coverage Tests (Python 3.11) (push) Has been cancelled
Details
Test / Offline Coverage Tests (Python 3.12) (push) Has been cancelled
Details
Test / Offline Coverage Tests (Python 3.13) (push) Has been cancelled
Details
Test / Offline Coverage Tests (Python 3.9) (push) Has been cancelled
Details
Test / Full Coverage (Python 3.11) (push) Has been cancelled
Details
Test / Core Provider Tests (OpenAI) (push) Has been cancelled
Details
Test / Core Provider Tests (Anthropic) (push) Has been cancelled
Details
Test / Core Provider Tests (Google) (push) Has been cancelled
Details
Test / Core Provider Tests (Other) (push) Has been cancelled
Details
Test / Anthropic Tests (push) Has been cancelled
Details
Test / Gemini Tests (push) Has been cancelled
Details
Test / Google GenAI Tests (push) Has been cancelled
Details
Test / Vertex AI Tests (push) Has been cancelled
Details
Test / OpenAI Tests (push) Has been cancelled
Details
Test / Writer Tests (push) Has been cancelled
Details
Test / Auto Client Tests (push) Has been cancelled
Details
ty / type-check (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:36:38 +08:00
commit 97e91a83f3
978 changed files with 159975 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/batch.md
+356
View File
@@ -0,0 +1,356 @@
---
title: Managing Batch Jobs with Multi-Provider CLI
description: Learn how to create, list, cancel, and delete batch jobs using the unified Command Line Interface (CLI) across OpenAI and Anthropic providers.
---
# Using the Command Line Interface for Batch Jobs
The instructor CLI provides comprehensive functionalities for managing batch jobs across multiple providers with a unified interface. This multi-provider support allows users to leverage the strengths of different AI providers for their batch processing needs.
## Supported Providers
- **OpenAI**: Utilizes OpenAI's robust batch processing capabilities with metadata support
- **Anthropic**: Leverages Anthropic's advanced language models with cancel/delete operations
The CLI uses a unified `--provider` flag for all commands, with backward compatibility for legacy flags.
```bash
$ instructor batch --help
Usage: instructor batch [OPTIONS] COMMAND [ARGS]...
Manage OpenAI Batch jobs
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ cancel Cancel a batch job │
│ create Create batch job using BatchProcessor │
│ create-from-file Create a batch job from a file │
│ delete Delete a completed batch job │
│ download-file Download the file associated with a batch job │
│ list See all existing batch jobs │
│ results Retrieve results from a batch job │
╰──────────────────────────────────────────────────────────────────────────────╯
```
## Creating a Batch Job
### List Jobs with Enhanced Display
```bash
$ instructor batch list --help
Usage: instructor batch list [OPTIONS]
See all existing batch jobs
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit INTEGER Total number of batch jobs │
│ to show │
│ [default: 10] │
│ --poll INTEGER Time in seconds to wait │
│ for the batch job to │
│ complete │
│ [default: 10] │
│ --screen --no-screen Enable or disable screen │
│ output │
│ [default: no-screen] │
│ --live --no-live Enable live polling to │
│ continuously update the │
│ table │
│ [default: no-live] │
│ --provider TEXT Provider to use (e.g., │
│ 'openai', 'anthropic') │
│ [default: openai] │
│ --use-anthropic --no-use-anthropic [DEPRECATED] Use --model │
│ instead. Use Anthropic API │
│ instead of OpenAI │
│ [default: │
│ no-use-anthropic] │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```
The enhanced list command now shows rich information including timestamps, duration, and provider-specific metrics:
```bash
$ instructor batch list --provider openai --limit 3
Openai Batch Jobs
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃ Batch ID ┃ Status ┃ Created ┃ Started ┃ Duration┃ Completed┃ Failed ┃ Total ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ batch_abc123... │ completed │ 07/07 │ 07/07 │ 2m │ 15 │ 0 │ 15 │
│ │ │ 23:48 │ 23:48 │ │ │ │ │
│ batch_def456... │ processing │ 07/07 │ 07/07 │ 45m │ 8 │ 0 │ 10 │
│ │ │ 22:30 │ 22:31 │ │ │ │ │
│ batch_ghi789... │ failed │ 07/07 │ N/A │ N/A │ 0 │ 5 │ 5 │
│ │ │ 21:15 │ │ │ │ │ │
└────────────────────┴────────────┴────────────┴────────────┴─────────┴──────────┴────────┴───────┘
$ instructor batch list --provider anthropic --limit 2
Anthropic Batch Jobs
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Batch ID ┃ Status ┃ Created ┃ Started ┃ Duration┃ Succeeded┃ Errored ┃ Processing ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ msgbatch_abc123... │ completed │ 07/08 │ 07/08 │ 1m │ 20 │ 0 │ 0 │
│ │ │ 03:47 │ 03:47 │ │ │ │ │
│ msgbatch_def456... │ processing │ 07/08 │ 07/08 │ 15m │ 5 │ 0 │ 10 │
│ │ │ 03:30 │ 03:30 │ │ │ │ │
└──────────────────────┴────────────┴────────────┴────────────┴─────────┴──────────┴─────────┴─────────────┘
```
### Create From File with Metadata Support
You can create batch jobs directly from pre-formatted .jsonl files with enhanced metadata support:
```bash
$ instructor batch create-from-file --help
Usage: instructor batch create-from-file [OPTIONS]
Create a batch job from a file
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --file-path TEXT File containing the │
│ batch job requests │
│ [default: None] │
│ [required] │
│ --model TEXT Model in format │
│ 'provider/model-name' │
│ (e.g., 'openai/gpt-5.4-mini', │
│ 'anthropic/claude-3-s… │
│ [default: │
│ openai/gpt-4o-mini] │
│ --description TEXT Description/metadata │
│ for the batch job │
│ [default: Instructor │
│ batch job] │
│ --completion-window TEXT Completion window for │
│ the batch job (OpenAI │
│ only) │
│ [default: 24h] │
│ --use-anthropic --no-use-anthropic [DEPRECATED] Use │
│ --model instead. Use │
│ Anthropic API instead │
│ of OpenAI │
│ [default: │
│ no-use-anthropic] │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```
Example usage with metadata:
```bash
# OpenAI batch with custom metadata
instructor batch create-from-file \
--file-path batch_requests.jsonl \
--model "openai/gpt-5-nano" \
--description "Email classification batch - production v2.1" \
--completion-window "24h"
# Anthropic batch
instructor batch create-from-file \
--file-path batch_requests.jsonl \
--model "anthropic/claude-3-5-sonnet-20241022" \
--description "Text analysis batch"
```
For creating .jsonl files, you can use the enhanced `BatchProcessor`:
```python
from instructor.batch import BatchProcessor
from pydantic import BaseModel, Field
from typing import Literal
class Classification(BaseModel):
label: Literal["SPAM", "NOT_SPAM"] = Field(
..., description="Whether the email is spam or not"
)
# Create processor
processor = BatchProcessor("openai/gpt-5-nano", Classification)
# Prepare message conversations
messages_list = [
[
{"role": "system", "content": "Classify the following email"},
{"role": "user", "content": "Hello there I'm a Nigerian prince and I want to give you money"}
],
[
{"role": "system", "content": "Classify the following email"},
{"role": "user", "content": "Meeting with Thomas has been set at Friday next week"}
]
]
# Create batch file
processor.create_batch_from_messages(
messages_list=messages_list,
file_path="batch_requests.jsonl",
max_tokens=100,
temperature=0.1
)
```
## Job Management Operations
### Cancelling a Batch Job
Cancel running batch jobs across all providers:
```bash
$ instructor batch cancel --help
Usage: instructor batch cancel [OPTIONS]
Cancel a batch job
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --batch-id TEXT Batch job ID to cancel │
│ [default: None] │
│ [required] │
│ --provider TEXT Provider to use (e.g., │
│ 'openai', 'anthropic') │
│ [default: openai] │
│ --use-anthropic --no-use-anthropic [DEPRECATED] Use │
│ --provider 'anthropic' │
│ instead. Use Anthropic API │
│ instead of OpenAI │
│ [default: │
│ no-use-anthropic] │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```
Examples:
```bash
# Cancel OpenAI batch
instructor batch cancel --batch-id batch_abc123 --provider openai
# Cancel Anthropic batch
instructor batch cancel --batch-id msgbatch_def456 --provider anthropic
```
### Deleting a Batch Job
Delete completed batch jobs (supported by Anthropic):
```bash
$ instructor batch delete --help
Usage: instructor batch delete [OPTIONS]
Delete a completed batch job
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --batch-id TEXT Batch job ID to delete [default: None] [required] │
│ --provider TEXT Provider to use (e.g., 'openai', 'anthropic') │
│ [default: openai] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```
Examples:
```bash
# Delete Anthropic batch (supported)
instructor batch delete --batch-id msgbatch_abc123 --provider anthropic
# Try to delete OpenAI batch (shows helpful message)
instructor batch delete --batch-id batch_ghi789 --provider openai
# Note: OpenAI does not support batch deletion via API
```
### Retrieving Batch Results
Get structured results from completed batch jobs:
```bash
$ instructor batch results --help
Usage: instructor batch results [OPTIONS]
Retrieve results from a batch job
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --batch-id TEXT Batch job ID to get results from │
│ [default: None] │
│ [required] │
│ * --output-file TEXT File to save the results to [default: None] │
│ [required] │
│ --model TEXT Model in format 'provider/model-name' (e.g., │
│ 'openai/gpt-5.4-mini', 'anthropic/claude-3-sonnet') │
│ [default: openai/gpt-4o-mini] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```
Examples:
```bash
# Get OpenAI batch results
instructor batch results \
--batch-id batch_abc123 \
--output-file openai_results.jsonl \
--model "openai/gpt-5-nano"
# Get Anthropic batch results
instructor batch results \
--batch-id msgbatch_def456 \
--output-file anthropic_results.jsonl \
--model "anthropic/claude-3-5-sonnet-20241022"
```
### Downloading Raw Files (Legacy)
For compatibility, the download-file command is still available:
```bash
$ instructor batch download-file --help
Usage: instructor batch download-file [OPTIONS]
Download the file associated with a batch job
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --batch-id TEXT Batch job ID to download │
│ [default: None] │
│ [required] │
│ * --download-file-path TEXT Path to download file to │
│ [default: None] │
│ [required] │
│ --provider TEXT Provider to use (e.g., 'openai', │
│ 'anthropic') │
│ [default: openai] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```
## Provider Support Matrix
| Operation | OpenAI | Anthropic |
|-----------|--------|-----------|
| **List** | ✅ Enhanced table | ✅ Enhanced table |
| **Create** | ✅ With metadata | ✅ File-based |
| **Cancel** | ✅ Standard API | ✅ Standard API |
| **Delete** | ❌ Not supported | ✅ Standard API |
| **Results** | ✅ Structured parsing | ✅ Structured parsing |
## Enhanced Features
- **Rich CLI Tables**: Color-coded status, timestamps, duration calculations
- **Metadata Support**: Add descriptions and custom fields to organize batches
- **Unified Commands**: Same interface works across all providers
- **Provider Detection**: Automatic provider detection from model strings
- **Error Handling**: Clear error messages and helpful notes for unsupported operations
- **Backward Compatibility**: Legacy flags still work with deprecation warnings
This comprehensive CLI interface provides efficient batch job management across all supported providers with enhanced monitoring and control capabilities.
docs/cli/finetune.md
+153
View File
@@ -0,0 +1,153 @@
---
title: Managing Fine-Tuning Jobs with the Instructor CLI
description: Learn how to create, view, and manage fine-tuning jobs on OpenAI using the Instructor CLI, with essential commands and options.
---
# Using the Command Line Interface
The instructor CLI provides functionalities for managing fine-tuning jobs on OpenAI.
!!! warning "Incomplete API"
The CLI is still under development and does not yet support all features of the API. If you would like to use a feature that is not yet supported, please consider using the contributing to our library [jxnl/instructor](https://www.github.com/jxnl/instructor) instead.
!!! note "Low hanging fruit"
If you want to contribute we're looking for a few things:
1. Adding filenames on upload
## Creating a Fine-Tuning Job
### View Jobs Options
```sh
$ instructor jobs --help
Usage: instructor jobs [OPTIONS] COMMAND [ARGS]...
Monitor and create fine tuning jobs
╭─ Options ───────────────────────────────────────────────────────────────────────────────╮
│ --help Display the help message. │
╰─────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ cancel Cancel a fine-tuning job. │
│ create-from-file Create a fine-tuning job from a file. │
│ create-from-id Create a fine-tuning job from an existing ID. │
│ list Monitor the status of the most recent fine-tuning jobs. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
### Create from File
The create-from-file command uploads and trains a model in a single step.
```sh
❯ instructor jobs create-from-file --help
Usage: instructor jobs create-from-file [OPTIONS] FILE
Create a fine-tuning job from a file.
╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────╮
│ * file TEXT Path to the file for fine-tuning [default: None] [required] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Model to use for fine-tuning [default: gpt-5.4-mini] │
│ --poll INTEGER Polling interval in seconds [default: 2] │
│ --n-epochs INTEGER Number of epochs for fine-tuning │
│ --batch-size TEXT Batch size for fine-tuning │
│ --learning-rate-multiplier TEXT Learning rate multiplier for fine-tuning │
│ --validation-file TEXT Path to the validation file [default: None] │
│ --model-suffix TEXT Suffix to identify the model [default: None] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────
```
#### Usage
```sh
$ instructor jobs create-from-file transformed_data.jsonl --validation_file validation_data.jsonl --n_epochs 3 --batch_size 16 --learning_rate_multiplier 0.5
```
### Create from ID
The create-from-id command uses an uploaded file and trains a model
```sh
❯ instructor jobs create-from-id --help
Usage: instructor jobs create-from-id [OPTIONS] ID
Create a fine-tuning job from an existing ID.
╭─ Arguments ───────────────────────────────────────────────────────────────────────────╮
│ * id TEXT ID of the existing fine-tuning job [default: None] [required] │
╰───────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Model to use for fine-tuning │
│ [default: gpt-5.4-mini] │
│ --n-epochs INTEGER Number of epochs for fine-tuning │
│ --batch-size TEXT Batch size for fine-tuning │
│ --learning-rate-multiplier TEXT Learning rate multiplier for fine-tuning │
│ --validation-file-id TEXT ID of the uploaded validation file │
│ [default: None] │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────╯
```
#### Usage
```sh
$ instructor files upload transformed_data.jsonl
$ instructor files upload validation_data.jsonl
$ instructor files list
...
$ instructor jobs create_from_id <file_id> --validation_file <validation_file_id> --n_epochs 3 --batch_size 16 --learning_rate_multiplier 0.5
```
### Viewing Files and Jobs
#### Viewing Jobs
```sh
$ instructor jobs list
OpenAI Fine Tuning Job Monitoring
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ ┃ ┃ ┃ Completion ┃ ┃ ┃ ┃ ┃
┃ Job ID ┃ Status ┃ Creation Time ┃ Time ┃ Model Name ┃ File ID ┃ Epochs ┃ Base Model ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ ftjob-PWo6uwk... │ 🚫 cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │
│ │ │ 23:10:54 │ │ │ │ │ │
│ ftjob-1whjva8... │ 🚫 cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │
│ │ │ 22:47:05 │ │ │ │ │ │
│ ftjob-wGoBDld... │ 🚫 cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │
│ │ │ 22:44:12 │ │ │ │ │ │
│ ftjob-yd5aRTc... │ ✅ succeeded │ 2023-08-23 │ 2023-08-23 │ ft:gpt-3.5-tur... │ file-IQxAUDqX... │ 3 │ gpt-5.4-mini-... │
│ │ │ 14:26:03 │ 15:02:29 │ │ │ │ │
└────────────────┴──────────────┴────────────────┴────────────────┴─────────────────┴────────────────┴────────┴─────────────────┘
Automatically refreshes every 5 seconds, press Ctrl+C to exit
```
#### Viewing Files
```sh
$ instructor files list
OpenAI Files
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃ File ID ┃ Size (bytes) ┃ Creation Time ┃ Filename ┃ Purpose ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ file-0lw2BSNRUlXZXRRu2beCCWjl │ 369523 │ 2023-08-23 23:31:57 │ file │ fine-tune │
│ file-IHaUXcMEykmFUp1kt2puCDEq │ 369523 │ 2023-08-23 23:09:35 │ file │ fine-tune │
│ file-ja9vRBf0FydEOTolaa3BMqES │ 369523 │ 2023-08-23 22:42:29 │ file │ fine-tune │
│ file-F7lJg6Z47CREvmx4kyvyZ6Sn │ 369523 │ 2023-08-23 22:42:03 │ file │ fine-tune │
│ file-YUxqZPyJRl5GJCUTw3cNmA46 │ 369523 │ 2023-08-23 22:29:10 │ file │ fine-tune │
└───────────────────────────────┴──────────────┴─────────────────────┴──────────┴───────────┘
```
# Contributions
We aim to provide a light wrapper around the API rather than offering a complete CLI. Contributions are welcome! Please feel free to make an issue at [jxnl/instructor/issues](https://github.com/jxnl/instructor/issues) or submit a pull request.
docs/cli/index.md
+113
View File
@@ -0,0 +1,113 @@
---
title: Instructor CLI Tools
description: Command-line utilities for monitoring API usage, fine-tuning models, and accessing documentation.
---
# Instructor CLI Tools
<div class="grid cards" markdown>
- :material-console: **Command Line Utilities**
Powerful tools to enhance your Instructor workflow
[:octicons-arrow-right-16: View Commands](#available-commands)
- :material-chart-line: **Usage Monitoring**
Track API usage, costs, and token consumption
[:octicons-arrow-right-16: Usage Guide](usage.md)
- :material-tune-vertical: **Model Fine-Tuning**
Create and manage custom model versions
[:octicons-arrow-right-16: Fine-Tuning Guide](finetune.md)
- :material-book-open-variant: **Documentation Access**
Quickly access docs from your terminal
[:octicons-arrow-right-16: Docs Command](#documentation-command)
</div>
## Getting Started
### Installation
The CLI tools are included with the Instructor package:
```bash
pip install instructor
```
### API Setup
Set your OpenAI API key as an environment variable:
```bash
export OPENAI_API_KEY="your-api-key-here"
```
## Available Commands
Instructor provides several command-line utilities:
| Command | Description | Guide |
|---------|-------------|-------|
| `instructor usage` | Track API usage and costs | [Usage Guide](usage.md) |
| `instructor finetune` | Create and manage fine-tuned models | [Fine-Tuning Guide](finetune.md) |
| `instructor docs` | Quick access to documentation | [See below](#documentation-command) |
## Usage Command
Monitor your OpenAI API usage directly from the terminal:
```bash
# View total usage for the current month
instructor usage
# View usage breakdown by day
instructor usage --by-day
# Calculate cost for a specific model
instructor usage --model gpt-5.4-mini
```
For detailed usage statistics and options, see the [Usage Guide](usage.md).
## Fine-Tuning Command
Create and manage fine-tuned models with an interactive interface:
```bash
# Start the fine-tuning interface
instructor finetune
```
This launches an interactive application that guides you through the fine-tuning process. Learn more in the [Fine-Tuning Guide](finetune.md).
## Documentation Command
Quickly access Instructor documentation from your terminal:
```bash
# Open main documentation
instructor docs
# Search for specific topic
instructor docs validation
# Open specific page
instructor docs concepts/models
```
This command opens the Instructor documentation in your default web browser, making it easy to find information when you need it.
## Support & Contribution
- **GitHub**: Visit our [GitHub Repository](https://github.com/jxnl/instructor)
- **Issues**: Report bugs or request features on our [Issue Tracker](https://github.com/jxnl/instructor/issues)
- **Discord**: Join our [Discord Community](https://discord.gg/bD9YE9JArw) for support
docs/cli/usage.md
+61
View File
@@ -0,0 +1,61 @@
---
title: OpenAI API Usage CLI Guide
description: Learn how to monitor OpenAI API usage with the CLI tool, including commands for viewing data by model, date, and cost.
---
# Using the OpenAI API Usage CLI
The OpenAI API Usage CLI tool provides functionalities for monitoring your OpenAI API usage, breaking it down by model, date, and cost.
## Monitoring API Usage
### View Usage Options
```sh
$ instructor usage --help
Usage: instructor usage [OPTIONS] COMMAND [ARGS]...
Check OpenAI API usage data
╭─ Options ───────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────╮
│ list Displays OpenAI API usage data for the past N days. │
╰─────────────────────────────────────────────────────────────────╯
```
### List Usage for Specific Number of Days
To display API usage for the past 3 days, use the following command:
```sh
$ instructor usage list --n 3
```
This will output a table similar to:
```plaintext
Usage Summary by Date, Snapshot, and Cost
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Date ┃ Snapshot ID ┃ Total Requests ┃ Total Cost ($) ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ 2023-09-04 │ gpt-5.4-mini │ 44 │ 0.68 │
│ 2023-09-04 │ gpt-5.4-mini │ 195 │ 0.84 │
│ 2023-09-04 │ text-embedding-ada-002-v2 │ 276 │ 0.00 │
│ 2023-09-04 │ gpt-4-32k-0613 │ 328 │ 49.45 │
└────────────┴───────────────────────────┴────────────────┴────────────────┘
```
### List Usage for Today
To display the API usage for today, simply run:
```sh
$ instructor usage list
```
# Contributions
We aim to provide a light wrapper around the API rather than offering a complete CLI. Contributions are welcome! Please feel free to make an issue at [jxnl/instructor/issues](https://github.com/jxnl/instructor/issues) or submit a pull request.