Overview¶

Full Instructor setup consists of following steps: - Step 1: Install Instructor via Composer - Step 2: Publish Instructor assets (configurations and prompts) to your project directory - Step 3: Set up LLM provider API key(s) in your .env file - Step 4: Set configuration location in your .env file (optional)

Step 1: Install Instructor via Composer¶

You can install Instructor via Composer by running:

composer require cognesy/instructor-php

Step 2: Publish Instructor Files to Your Project¶

Instructor comes with a set of configuration files and prompt templates that you can publish to your project directory.

This will allow you to customize the library's behavior and use different prompt templates.

These files can be found in the vendor/cognesy/instructor-php directory: - .env-dist - Environment variables for API keys and configuration paths - /config/*.php - Configurations of Instructor modules - /prompts/* - Prompt templates for generating structured data from text

You can publish these files to your project directory by running following command:

./vendor/bin/instructor-setup publish \n
  --target-config-dir=<target config dir location>
  --target-prompts-dir=<target prompts dir location>
  --target-env-file=<target .env file location>

You can also manually copy the required files to your project directory.

Step 3: Set Up LLM Provider API Key(s)¶

If you're using commercial LLM providers like OpenAI, you'll need to set up API keys in your project's .env file.

Open the .env file in your project directory and set up API keys for the LLM providers you plan to use. You can find the keys in the respective provider's dashboard.

```ini .env

OpenAI (default provider)¶

OPENAI_API_KEY='your-openai-api-key'

Check `.env-dist` for other API keys Instructor uses in its default configuration files.


### Step 4: Set Configuration Location (optional)

Instructor uses a configuration directory to store its settings, e.g. LLM provider configurations.

You can set the path to this directory via `Settings::setPath('/path/to/config')` in your code.

But to make it easier you can just set the value in your `.env` file. `Settings` will pick it up automatically
from there. This way you don't have to set it in every script.

```ini .env
INSTRUCTOR_CONFIG_PATHS='/path/to/your/config/dir/,another/path'

INSTRUCTOR_CONFIG_PATHS is set automatically if you use the Instructor CLI tool to publish assets.

Framework Integration¶

Laravel Projects¶

For Laravel applications, it's recommended to align with the framework's directory structure:

./vendor/bin/instructor-setup publish \
    --target-config-dir=config/instructor \
    --target-prompts-dir=resources/prompts \
    --target-env-file=.env

This will: - Place configuration files in Laravel's config directory - Store prompts in Laravel's resources directory - Use Laravel's default .env file location

After publishing, you can load Instructor configuration in your config/app.php or create a dedicated service provider.

Symfony Projects¶

For Symfony applications, use the standard Symfony directory structure:

./vendor/bin/instructor-setup publish \
    --target-config-dir=config/packages/instructor \
    --target-prompts-dir=resources/instructor/prompts \
    --target-env-file=.env

This will: - Place configuration in Symfony's package configuration directory - Store prompts in Symfony's resources directory - Use Symfony's default .env file location

For Symfony Flex applications, you may want to create a recipe to automate this setup process.

Custom Framework Location¶

You can use environment variables to set the location of configuration files:

INSTRUCTOR_CONFIG_PATHS=/path/to/config,another/path

This allows you to maintain consistent paths across your application without specifying them in each command.

Using CLI Tool¶

After installing Instructor via Composer, you may want to publish the library's configuration files and resources to your project, so you can modify them according to your needs. You can do this either manually or automatically using the provided CLI tool.

./vendor/bin/instructor-setup publish

By default, this command will: 1. Copy configuration files from vendor/cognesy/instructor-php/config to config/instructor/ 2. Copy prompt templates from vendor/cognesy/instructor-php/prompts to resources/prompts/ 3. Merge (or copy) vendor/cognesy/instructor-php/.env-dist file to .env with environment variables

Command Options¶

-c, --target-config-dir=DIR - Custom directory for configuration files (default: config/instructor)
-p, --target-prompts-dir=DIR - Custom directory for prompt templates (default: resources/prompts)
-e, --target-env-file=FILE - Custom location for .env file (default: .env)
-l, --log-file=FILE - Optional log file path to track the publishing process
--no-op - Dry run mode - shows what would be copied without making changes

Example Usage¶

./vendor/bin/instructor-setup publish \
    --target-config-dir=./config/instructor \
    --target-prompts-dir=./resources/prompts \
    --target-env-file=.env

When merging .env files, the tool will only add missing variables, preserving your existing file content, formatting and comments.

Manual Setup¶

If you prefer to set up Instructor manually or need more control over the process, you can copy the required files directly:

Configuration Files¶

# Create config in your preferred directory
mkdir -p config/instructor

# Copy configuration files
cp -r vendor/cognesy/instructor-php/config/* config/instructor/

These files contain LLM API connection settings and Instructor's behavior configuration.

Prompt Templates¶

# Create prompts in your preferred directory
mkdir -p resources/prompts

# Copy prompt templates
cp -r vendor/cognesy/instructor-php/prompts/* resources/prompts/

Prompt templates define how Instructor communicates with LLMs for different tasks.

Environment Configuration¶

If .env doesn't exist, copy the environment template:

[ ! -f .env ] && cp vendor/cognesy/instructor-php/config/.env-dist .env

Add key values to your .env:

# OpenAI API key
OPENAI_API_KEY=your_api_key
# Other API keys (if you use other LLM providers)
# ...

# Set up Instructor configuration path (optional)
INSTRUCTOR_CONFIG_PATHS='<path/to/config>,<another/path>'