Skip to content

Self-improving AI Employees for everyone

8.4 KB
Raw Blame

OpenAI Chat Model (openaiChatModel)

Field Value
Category ai_chat_models
Backend handler server/nodes/model/openai_chat_model/__init__.py (dispatch via BaseNode.execute() -> @Operation("chat") in server/nodes/model/_base.py)
AI service server/services/ai.py::AIService.execute_chat
Tests server/tests/nodes/test_ai_chat_models.py
Skill (if any) n/a
Dual-purpose tool yes - tool name openai_chat_model (advisor; usable_as_tool = True, group ('model', 'tool'))

Purpose

Single-turn chat completion against the OpenAI API. Used either as a standalone workflow node (user enters a prompt, the node produces a response), wired into an AI Agent via the input-model handle, or connected as an advisor tool (usable_as_tool = True). Every chat-model node runs through the shared ChatModelBase.chat operation (in _base.py), which calls provider-neutral AIService.execute_chat; OpenAI-specific request policy lives in the native provider and shared model-policy helpers.

Inputs (handles)

Handle Connection type Required Purpose
input-main main no Upstream data; not consumed directly by the handler - prompt must be passed via parameters or template-resolved upstream

Parameters

Name Type Default Required displayOptions.show Description
prompt string "" yes (non-empty) - User message content sent to the model
system_prompt string "" no - System prompt
model string "" (injected from stored models) no - Model ID. [FREE] prefix is stripped before the API call
temperature number|null null -> agent.default_temperature no - 0-2 for most OpenAI models; o-series (o1/o3/o4) force temperature=1
max_tokens number|null null -> per-model default no - 1-200000; clamped via _resolve_max_tokens to the model's actual ceiling
top_p number|null 1.0 no - Nucleus sampling
frequency_penalty number|null 0.0 no - -2.0 to 2.0
presence_penalty number|null 0.0 no - -2.0 to 2.0
response_format enum text no - text or json_object
thinking_enabled boolean false no - Turn on extended reasoning (GPT-5 hybrid / o-series)
reasoning_effort enum medium no thinking_enabled=[true] minimal / low / medium / high (OpenAI override adds minimal)
api_key string|null null (injected) no - auth_service.get_api_key('openai', 'default')

(Field names are snake_case on OpenAIChatModelParams; model_config = ConfigDict(extra="ignore") drops unknown keys.)

Outputs (handles)

Handle Shape Description
output-model object Model output (also feeds an agent's input-model handle); standard envelope payload (see below)

Output payload

{
  response: string;
  thinking: string | null;
  thinking_enabled: boolean;
  model: string;
  provider: 'openai';
  finish_reason: string;
  timestamp: string;  // ISO 8601
  input: { prompt: string; system_prompt: string };
}

Wrapped in the standard envelope: { success: true, node_id, node_type, result: <payload>, execution_time: number }.

Logic Flow

flowchart TD
  A[NodeExecutor dispatch -> BaseNode.execute] --> B[ChatModelBase.chat Operation<br/>params validated by Pydantic]
  B --> C[get_ai_service]
  C --> D[AIService.execute_chat]
  D --> E[Flatten options into flat params dict]
  E --> F{api_key present?}
  F -- no --> X[raise ValueError -> error envelope]
  F -- yes --> G{prompt non-empty?}
  G -- no --> X
  G -- yes --> H[detect_ai_provider -> 'openai']
  H --> I[Build NativeThinkingConfig if thinkingEnabled]
  I --> J[Lookup openai_proxy credential]
  J --> K[ChatUnifier.chat provider='openai']
  K --> L[registry.get_provider openai + OpenAI SDK<br/>await provider.chat]
  L --> M[Build response dict<br/>response / thinking / model / provider / finish_reason]
  M --> N[Return success envelope]
  L -- Exception --> X

Decision Logic

  • Validation: missing api_key -> ValueError; empty/whitespace prompt (via is_valid_message_content) -> ValueError. Both produce a success=false envelope.
  • Provider routing: detect_ai_provider(node_type) returns 'openai' for this node; falls through the else branch in constants.detect_ai_provider.
  • Native path: ChatUnifier resolves the self-registered openai spec, so the native openai SDK serves both current chat and agent executions. LangChain remains isolated to eligible Temporal-history replay.
  • Model ID handling: strips only the UI-only [FREE] decoration. Provider model IDs are otherwise opaque and preserved.
  • Thinking config: only built when thinkingEnabled is truthy; passed through to the provider's chat() method.
  • System prompt: reads the schema-canonical system_prompt field and prepends a native Message(role="system") when it is non-empty.
  • Error path: typed SDK failures are translated by ChatUnifier into NodeUserError and re-raised to BaseNode.execute(); unexpected exceptions are logged and returned as success=false.

Side Effects

  • Database writes: none directly in the happy path. _track_token_usage (invoked elsewhere in the AI service when memory is attached) writes TokenUsageMetric rows; for a bare chat model node with no memory this path is typically not exercised from execute_chat.
  • Broadcasts: none from execute_chat itself.
  • External API calls: the standalone chat node uses OpenAI Chat Completions through the native SDK. Native agent turns that need reasoning continuation state use the Responses API; ordinary agent turns use Chat Completions. An openai_proxy credential can override the SDK endpoint.
  • File I/O: none.
  • Subprocess: none.

External Dependencies

  • Credentials: auth_service.get_api_key('openai', 'default') (API key); optional auth_service.get_api_key('openai_proxy') for proxy URL override.
  • Services: AIService (wired via NodeExecutor.__init__), services/llm/providers/openai.py (native provider).
  • Python packages: openai (native SDK).
  • Environment variables: none (keys are DB-stored).

Edge cases & known limits

  • Reasoning-model temperature: the native provider omits temperature for configured OpenAI reasoning models instead of forwarding an unsupported value.
  • GPT-5 hybrid reasoning: reasoningEffort (minimal / low / medium / high) is consumed via NativeThinkingConfig.effort and forwarded to the provider SDK. Without thinkingEnabled=true the effort value is ignored.
  • Reasoning summary availability: the content of thinking for o-series models is gated on OpenAI org verification - unverified orgs get thinking=null even with reasoningEffort set.
  • maxTokens clamp: clamped to the model's actual output ceiling by native_resolve_max_tokens. Exceeding the limit silently caps without error.
  • Error boundary: typed OpenAI SDK failures become user-safe NodeUserError values in ChatUnifier and are re-raised to BaseNode.execute(), which produces the standard failure envelope. Unexpected failures are logged and returned by execute_chat.
  • No streaming: execute_chat is single-shot; the full response is awaited before returning.
  • Pricing / token tracking: standalone chat model nodes do NOT trigger _track_token_usage - that lives on the agent code paths. Cost attribution for bare chat-model executions is therefore not recorded.

Related