Skip to content

API AI

Jump to bottom
Dory Azar edited this page Nov 15, 2026 · 2 revisions

AI

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

OpenAI, open models through OpenAI-compatible providers, the OpenAI Assistants and Watson.

Class What it is
Caligrafy\OpenAI The OpenAI class handles all exchanges with the OpenAI models (text and images)
Caligrafy\Agent The Agent class talks to open models through OpenAI-compatible providers: Groq (default, through groq-php), Together AI, Fireworks AI, OpenRouter, a local Ollama or any custom endpoint.
Caligrafy\Assistant The Assistant class runs conversations with OpenAI models through the Responses and Conversations APIs.
Caligrafy\Watson The Watson class handles all exchanges with the Watson Assistant

class Caligrafy\OpenAI

namespace Caligrafy;

class OpenAI extends \stdClass

Source: framework/core/OpenAI.php:22

The OpenAI class handles all exchanges with the OpenAI models (text and images)

Constants

  • COMMANDS = array('CONVERSE', 'SUMMARIZE', 'ANALYZE', 'CORRECT', 'CLASSIFY', 'COMPLETE', 'PREDICT', 'RECOMMEND', 'CUSTOM'): Commands that delegate() accepts, by name (case insensitive)
  • TYPES = array('TEXT', 'IMAGE'): Model types that the constructor accepts, by name (case insensitive)

Public properties

  • public $type: string the OpenAI model type: text or image
  • public $parameters: string the OpenAI model parameters
  • public $context: array conversation context
  • public $attachments: string the OpenAI file attachments necessary for fine-tuning models

Methods

OpenAI::command()

public static function command($name)

Resolves a command name (ex: 'summarize' from a form) to its prompt. Returns null for anything else, so that user input can never select another constant (such as APP_KEY or DB_PASSWORD)

Parameters

  • $name

Source: framework/core/OpenAI.php:38

OpenAI::type()

public static function type($name)

Resolves a model type name ('text' or 'image') to its configuration. Returns null for anything else

Parameters

  • $name

Source: framework/core/OpenAI.php:47

->__construct()

public function __construct($mode = TEXT)

No doc comment.

Parameters

  • $mode, default TEXT

Source: framework/core/OpenAI.php:87

->converse()

public function converse(
    $parameters = array(),
    $attachments = array(),
    $method = 'POST',
    $additionalHeaders = array()
)

General method to command the AI to converse in text parameters:

  • For type text: array of model, prompt/input, instructions, temperature, tokens, max_tokens, top_p, frequency_penalty
  • For type image: array of prompt, n, size

attachments:

  • For type image: array("image" => uri to image)

method: POST, GET, PUT, DELETE. default is POST additionalHeaders: array of request headers to complement default

Parameters

  • $parameters, default array()
  • $attachments, default array()
  • $method, default 'POST'
  • $additionalHeaders, default array()

Source: framework/core/OpenAI.php:109

->delegate()

public function delegate(
    $input = '',
    $outcome = '',
    $command = ANALYZE,
    $context = array(),
    $parameters = array()
)

No doc comment.

Parameters

  • $input, default ''
  • $outcome, default ''
  • $command, default ANALYZE
  • $context, default array()
  • $parameters, default array()

Source: framework/core/OpenAI.php:115

class Caligrafy\Agent

namespace Caligrafy;

class Agent extends \stdClass

Source: framework/core/Agent.php:33

The Agent class talks to open models through OpenAI-compatible providers: Groq (default, through groq-php), Together AI, Fireworks AI, OpenRouter, a local Ollama or any custom endpoint.

Choose the provider in .env with AGENT_PROVIDER (groq|together|fireworks|openrouter|ollama|custom). Key: the provider key (GROQ_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, OPENROUTER_API_KEY) or AGENT_API_KEY. AGENT_API_BASE overrides the endpoint (required for custom), AGENT_MODEL and AGENT_VISION_MODEL the default models. The GROQ_* settings and constants keep working as before.

Groq keeps groq-php: its audio endpoints (multipart uploads) and behavior stay unchanged. The other providers only need chat completions and the model list, sent with cURL (no extra dependency).

Constants

  • PROVIDERS = ...: Providers: label, default endpoint, key setting, default models (October 2026), audio support, where to get a key and where the models are listed. Ollama needs no key; custom needs AGENT_API_BASE and AGENT_MODEL. Serverless Llama (October 2026): OpenRouter and Ollama only. Groq retired its Llama chat models in August 2026, Together and Fireworks only serve Llama on dedicated/on-demand deployments: their defaults are gpt-oss-120b. Preview models: Groq qwen/qwen3.8-27b.
  • TIMEOUT = 120

Methods

->__construct()

public function __construct($apiKey = "", $provider = "", $baseUrl = "")

apiKey: optional key, otherwise taken from .env provider: optional provider name, otherwise AGENT_PROVIDER (default groq) baseUrl: optional endpoint, otherwise AGENT_API_BASE or the provider default

Parameters

  • $apiKey, default ""
  • $provider, default ""
  • $baseUrl, default ""

Source: framework/core/Agent.php:92

Agent::settings()

public static function settings($get = null, $provider = "", $baseUrl = "")

Resolves the provider settings from .env (or from $get, a function that returns a setting by name: used by doctor)

Parameters

  • $get, default null
  • $provider, default ""
  • $baseUrl, default ""

Returns array: provider, label, base, baseOverride, key, keyName, model, vision

Source: framework/core/Agent.php:118

Agent::setting()

public static function setting($name)

Reads a setting: $_ENV (filled from .env), then the constant of the same name, then getenv()

Parameters

  • $name

Source: framework/core/Agent.php:147

->provider()

public function provider()

Provider in use (groq, together, fireworks, openrouter, ollama or custom)

Source: framework/core/Agent.php:156

->model()

public function model()

Default text model of the provider (AGENT_MODEL, GROQ_MODEL for Groq, or the built-in default)

Source: framework/core/Agent.php:164

->visionModel()

public function visionModel()

Default vision model of the provider (AGENT_VISION_MODEL, GROQ_VISION_MODEL for Groq, or the built-in default)

Source: framework/core/Agent.php:172

->configure()

public function configure($parameters = array())

Set configuration of Agent parameters include: temperature, max_tokens etc. They are added to every delegate() and visualize() request.

Parameters

  • $parameters, default array()

Source: framework/core/Agent.php:181

->delegate()

public function delegate(
    $model = "",
    $messages = array(),
    $response_format = array(),
    $stream = false,
    $tool_choice = "",
    $tools = array()
)

Create a text prompt for agent model: specify the model of the provider (default: model()) messages: array of role (system, user) and content response_format: array of types i.e ['type' => 'json_object'] stream: set to true if streaming response is expected. Check documentation for fetching results tool_choice: set to "auto" when tools are used tools: array of tool definition (OpenAI format)

Parameters

  • $model, default ""
  • $messages, default array()
  • $response_format, default array()
  • $stream, default false
  • $tool_choice, default ""
  • $tools, default array()

Source: framework/core/Agent.php:196

->visualize()

public function visualize($file = "", $prompt = "Describe this image", $model = "")

Vision file: file path (or a public image URL that the provider downloads) prompt: what to do with image model: a vision model of the provider (default: visionModel())

Parameters

  • $file, default ""
  • $prompt, default "Describe this image"
  • $model, default ""

Source: framework/core/Agent.php:246

->transcribe()

public function transcribe(
    $file = "",
    $prompt = "",
    $model = GROQ_TRANSCRIPTION_MODEL,
    $language = "en",
    $response_format = "json"
)

Audio Transcribe (Groq only) file: file path model: specify model to use response_format: string. 'json' language: specify language of audio prompt: string of an optional transcription prompt

Parameters

  • $file, default ""
  • $prompt, default ""
  • $model, default GROQ_TRANSCRIPTION_MODEL
  • $language, default "en"
  • $response_format, default "json"

Source: framework/core/Agent.php:283

->translate()

public function translate(
    $file = "",
    $prompt = "",
    $model = GROQ_TRANSCRIPTION_MODEL,
    $response_format = "json"
)

Audio Translate (Groq only) file: file path model: specify model to use response_format: string. 'json' prompt: string of an optional transcription prompt

Parameters

  • $file, default ""
  • $prompt, default ""
  • $model, default GROQ_TRANSCRIPTION_MODEL
  • $response_format, default "json"

Source: framework/core/Agent.php:304

->models()

public function models()

Models of the provider (for Ollama: the models pulled on the server)

Returns array: ['api_success' => true, 'response' => sorted list of model ids] or ['api_success' => false, 'response' => error]

Source: framework/core/Agent.php:321

Agent::modelIds()

public static function modelIds($json)

Model ids of a GET /models answer: {data: [...]} (OpenAI, Groq, OpenRouter, Ollama /v1/models), a bare list (Together), or {models: [{name}]} (Ollama /api/tags, Fireworks account models). Models marked inactive (Groq) are left out.

Parameters

  • $json

Returns array|null: sorted ids, null when the answer is not a model list

Source: framework/core/Agent.php:336

class Caligrafy\Assistant

namespace Caligrafy;

class Assistant extends \stdClass

Source: framework/core/Assistant.php:29

The Assistant class runs conversations with OpenAI models through the Responses and Conversations APIs.

OpenAI shut down the Assistants API on August 26, 2026. Version 2.0 of this class keeps the same chainable methods (start, createMessage, run, retrieveResponse, end) on top of the APIs that replace it:

  • the assistant (model, instructions, tools) is configuration kept in this object and sent with every response
  • a conversation (POST /v1/conversations) replaces the thread
  • a response (POST /v1/responses) replaces the run
  • files are searched through a vector store (file_search tool)

Public properties

  • public $name: string the name of the assistant (used for the vector store name and metadata)
  • public $description: string what the assistant does (local description)
  • public $instructions: string the instructions (system prompt) sent with every response
  • public $tools = array(["type" => "file_search"]): array the tools: ["type" => "file_search"] is completed with the vector store, ["type" => "code_interpreter"] gets an automatic container with the uploaded files
  • public $file_ids =[]: array ids of the files uploaded for the assistant
  • public $file_paths =[]: array local paths of the files to upload
  • public $metadata: array metadata sent with every response (up to 16 string pairs)
  • public $vector_store_id = '': string the vector store that holds the files searched by file_search
  • public $assistant_id = '': string kept for backward compatibility: the Assistants API no longer exists, nothing is created on OpenAI
  • public $thread_id = '': string the active conversation id (conv_...). Kept under its old name for backward compatibility
  • public $run_id = '': string the last response id (resp_...)
  • public $status = 'queued': string the status of the last response: completed, failed, in_progress, queued, incomplete, cancelled
  • public $messages =[]: array the messages of the conversation: the user messages added and the assistant messages received. Every message is ['id', 'role', 'content' => 'type' => 'input_text']
  • public $response_text = '': string the text of the last assistant answer
  • public $last_response =[]: array the last raw response returned by OpenAI (useful for errors and usage)

Methods

->__construct()

public function __construct($parameters = array())

Configure an assistant parameters: name, description, instructions, model, tools, metadata, file_paths (uploaded to a new vector store), file_ids (already uploaded files), vector_store_id (existing vector store)

Parameters

  • $parameters, default array()

Source: framework/core/Assistant.php:130

->retrieve()

public function retrieve()

Kept for backward compatibility: the assistant configuration lives in this object

Source: framework/core/Assistant.php:154

->delete()

public function delete()

Deletes the vector store created for the assistant (the uploaded files stay in the OpenAI file storage)

Source: framework/core/Assistant.php:162

->start()

public function start()

Start the contextual conversation (POST /v1/conversations)

Source: framework/core/Assistant.php:177

->end()

public function end()

Delete the contextual conversation

Source: framework/core/Assistant.php:189

->createMessage()

public function createMessage($content, $file_ids =[], $metadata = null, $role = "user")

Add a message to send with the next run() $file_ids: files given to the code interpreter for this message

Parameters

  • $content
  • $file_ids, default []
  • $metadata, default null
  • $role, default "user"

Source: framework/core/Assistant.php:203

->listMessages()

public function listMessages()

Lists the items of the conversation (GET /v1/conversations/{id}/items), oldest first

Source: framework/core/Assistant.php:217

->run()

public function run(
    $additional_instructions = '',
    $instructions = null,
    $tools =[],
    $model = '',
    $metadata = null
)

Send the pending messages and get the answer (POST /v1/responses) The overrides apply to this response only

Parameters

  • $additional_instructions, default ''
  • $instructions, default null
  • $tools, default []
  • $model, default ''
  • $metadata, default null

Source: framework/core/Assistant.php:226

->retrieveResponse()

public function retrieveResponse($timeout = 120, $interval = 2)

Waits for the last response when it is still queued or in progress (background responses), polling GET /v1/responses/{id} every $interval seconds for at most $timeout seconds

Parameters

  • $timeout, default 120
  • $interval, default 2

Source: framework/core/Assistant.php:256

->text()

public function text()

Returns the text of the last assistant answer

Source: framework/core/Assistant.php:272

->uploadAssistantFiles()

public function uploadAssistantFiles($specified_paths =[])

Uploads files (POST /v1/files) and adds them to the assistant's vector store for file_search

Parameters

  • $specified_paths, default []

Returns array: the ids of the uploaded files

Source: framework/core/Assistant.php:281

->deleteAssistantFile()

public function deleteAssistantFile($file_id)

Removes a file from the vector store and deletes it from the OpenAI file storage

Parameters

  • $file_id

Source: framework/core/Assistant.php:303

class Caligrafy\Watson

namespace Caligrafy;

class Watson extends \stdClass

Source: framework/core/Watson.php:20

The Watson class handles all exchanges with the Watson Assistant

Methods

->__construct()

public function __construct($watson_assistant_id, $environment_id = null)

.env settings:

Parameters

  • $watson_assistant_id
  • $environment_id, default null

Source: framework/core/Watson.php:90

->communicate()

public function communicate($messageText, $skillVariables = null)

Send Input to Watson

Parameters

  • $messageText string: to send to Watson
  • $skillVariables array, default null

Source: framework/core/Watson.php:124

->getSessionId()

public function getSessionId()

Get Session ID

Returns the: current active session ID

Source: framework/core/Watson.php:157

->getContext()

public function getContext()

Get Context

Returns the: current Context

Source: framework/core/Watson.php:170

->getSkillVariables()

public function getSkillVariables()

Get Skill Variables

Returns the: skill variables

Source: framework/core/Watson.php:182

->getContextVariable()

public function getContextVariable($variable)

Get Context Variable

Parameters

  • $variable

Returns the: Context variable

Source: framework/core/Watson.php:196

->getConversation()

public function getConversation()

Get Context

Returns the: current Conversation

Source: framework/core/Watson.php:210

->getLastExchange()

public function getLastExchange()

Get Context

Returns the: last exchange

Source: framework/core/Watson.php:223

->getResponse()

public function getResponse()

Get Last Response

Returns the: last response

Source: framework/core/Watson.php:236

->getExchangeAt()

public function getExchangeAt($turnCount)

Get conversation exchange at turn count

Parameters

  • $turnCount int: defines the turn count of the conversation

Returns array: the conversation exchange at turn count

Source: framework/core/Watson.php:251

->closeSession()

public function closeSession()

Close the Watson Session

Returns boolean: true if session closed successfully

Source: framework/core/Watson.php:265

Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.

Start here

Why Caligrafy: the benefits, the measurements, and what it is not yet

  1. Quickstart with Claude: describe it, approve it, ship it

    or the Quickstart: the same three steps by hand, in 5 minutes

  2. How Caligrafy works: the ideas in 5 minutes
  3. Your first capability: build a feature, page included

Capabilities

Experiences

Data and people

  1. Models
  2. Relationships
  3. Queries: filters, paging, related rows
  4. Sign-in, users and tokens

Built-in features

Put it online

Build with AI

Reference

Clone this wiki locally