Basic Tool Calling Seems to be Undocumented with Instructor

[griffin-norris]

Is your feature request related to a problem? Please describe. Based on the available documentation it is not clear how to support standard function/tool calling while using Instructor.

Describe the solution you'd like Ideally I would want to be able to provide arbitrary additional tools similar to the openai function calling guide, or, if this is already supported, have a more clear documentation section for this

[KennyVaneetvelde]

Why would you want this? This abstracts away things that should not be abstracted away. Instead, try to embrace it and lean into it like https://github.com/BrainBlend-AI/atomic-agents does.

In the end, all an LLM does is output data, so that means if you choose to make your LLM have an output schema that corresponds with the parameters of a tool, that is a tool call. It is up to your code to choose what to do with this.

This might seem inflexible, but in reality, it is the most flexible option out there, as you are now free to interject anything into it, like logging and observability tools that are not made to solve problems that don't exist and cost you an extra $50/month.

I highly recommend having a look at this: https://github.com/BrainBlend-AI/atomic-agents/blob/main/atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py

[Mr-Ruben]

I agree with Kenny.

Instructor does this (kind of)

%%{init: {'theme':'forest','layout':'elk','look':'neo'}}%%
flowchart TD

  %% Step 1: Declare nodes
  IN["Instructor Library"]
  LLM["LLM (Large Language Model)"]
  PD["Pydantic Model"]
  PRM{{"Prompt"}}
  RSP{{"LLM Response"}}
  VAL["Validation"]
  OUT["Structured Output"]

  %% Step 2: Declare subgraph for Instructor's workflow
  subgraph INST["Instructor Workflow"]
    PRM & LLM & RSP & VAL
  end

  %% Step 3: Connect nodes with labels
  IN -->|"prepares prompt"| PRM
  PRM -->|"sent to"| LLM
  LLM -->|"generates"| RSP
  RSP -->|"parsed into"| PD
  PD -->|"validated by"| VAL
  VAL -->|"returns"| OUT

  %% Two-way connection for error handling
  VAL -.->|"validation error"| LLM

  %% Instructor orchestrates the whole process
  IN -->|"uses"| PD
  IN -->|"calls"| LLM
  IN -->|"handles"| VAL

which could be summarized like

%%{init: {'theme':'forest','layout':'elk','look':'neo'}}%%
flowchart TD

%% ==== GUIDELINES for Mermaid flowchart ====
%% Step 1: Declare all NODES without connections.

TXT["Text"]
LLM["LLM"]
SOUT["Structured Output"]
INST["Instructor"]
PRM["Pydantic response_model instance"]

%% Step 2: No subgraphs needed for this flow.

%% Step 3: Declare all CONNECTIONS with appropriate LABELS.

TXT -->|"sent as prompt"| LLM
LLM -->|"returns"| SOUT
SOUT -->|"processed by"| INST
INST -->|"validated & parsed"| PRM

I call it a 'template filler'. If with the text received in the template you want to 'call a tool', you have to do it, not Instructor.

This may help you https://github.com/567-labs/instructor/discussions/732