AI Chat ExecModule

Overview

AiChatModule sends one bounded prompt through ValkyrAI's shared LlmAdapterFactory. It supports OpenAI and explicitly configured Ollama-compatible endpoints. The module can return ordinary text or validate a strict JSON command proposal for a later policy-controlled dispatcher.

The module does not execute model-proposed commands. OpenAI credentials are read only from the IntegrationAccount bound to ExecModuleConfig.authConfig.integrationAccount; prompt inputs and legacy direct-key fields are never credential sources.

Usage

1. Bind an OpenAI IntegrationAccount, or configure a trusted Ollama-compatible endpoint.
2. Add AiChatModule to a workflow task.
3. Select text or json_commands response mode.
4. Map a non-empty prompt from a prior step or workflow input.
5. Treat commands as untrusted proposals and send them through authorization, approval, and execution policy before acting.

Inputs

Name	Type	Required	Default	Description
prompt	string	Yes	None	User prompt sent to the provider.
systemPrompt	string	No	Safe built-in assistant instruction	System instruction. In json_commands mode, the strict command schema is appended.
responseMode	string	No	text	text or json_commands; an input value overrides the configured default.

The module rejects a blank prompt and unsupported response modes before any provider call.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
provider	string	Always	Normalized provider name.
model	string	Always	Requested model identifier.
attempts	integer	Always	0 before a provider call or 1 once submitted.
content	string	Success	Provider response content.
commands	array	Success	Validated proposals; empty in text mode. Each entry has a non-empty name and object args.
error	object	Failure	Bounded {code, message, retryable} details with secret-like text redacted.

IntegrationAccount Requirements

OpenAI executions require an IntegrationAccount relationship on the module auth config.

Field	Requirement
accountName	Human-readable OpenAI account label.
apiKey	Encrypted SecureField containing the OpenAI API key.
status	ready or an unset legacy value. closed and error fail closed.

Do not place an API key in prompt, systemPrompt, payload parameters, or the deprecated openAiApiKey field. Ollama mode does not require an IntegrationAccount, but ollamaModelUrl must point to a trusted endpoint selected by the workflow operator.

Configuration

Name	Type	Default	Constraints
llmAccount	IntegrationAccount	None	Required for OpenAI; bind through the generated auth relationship.
provider	select	OPENAI	OPENAI or OLLAMA. Other generated provider enum values fail closed.
openAiModel	string	gpt-4o	Provider model identifier; used by both supported transports.
ollamaModelUrl	URL	None	Required for OLLAMA. Network trust and allow-listing remain deployment responsibilities.
temperature	number	0.0	0 through 2.
responseMode	select	text	text or json_commands.
systemPrompt	multiline string	Built-in default	Optional system instruction.
timeoutSeconds	integer	60	1 through 300 seconds.

Illustrative normalized configuration:

{
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:openai-production"
  },
  "payloadConfig": {
    "parameters": "{\"provider\":\"OPENAI\",\"openAiModel\":\"approved-model-id\",\"responseMode\":\"json_commands\",\"temperature\":0}"
  }
}

The symbolic account value is documentation only. Persisted workflows use the generated IntegrationAccount relationship, not plaintext credentials.

Operations

AiChatModule has one completion operation with two response contracts:

Mode	Provider contract	Side effect
text	Returns non-empty provider text and an empty command list.	Sends prompt content to the selected provider and may consume provider credits.
json_commands	Requires exactly one JSON object containing a commands array. Each command needs a non-empty string name and object args; at most 100 commands are accepted.	Same outbound/provider-billing effect. Commands are returned but never executed.

Errors and Failure Modes

Code	Cause	Retryable	Resolution
VALIDATION_ERROR	Blank prompt, bad response mode, invalid temperature/timeout, or missing Ollama URL.	No	Correct configuration before retrying.
UNSUPPORTED_PROVIDER	A generated provider enum not implemented by this module was selected.	No	Use OpenAI or Ollama.
INTEGRATION_ACCOUNT_REQUIRED	OpenAI has no bound account.	No	Bind an OpenAI IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	The account is closed or in an error state.	No	Repair or reconnect the account.
INTEGRATION_ACCOUNT_INVALID	The account has no readable API key SecureField.	No	Store the key in the generated encrypted field and verify decrypt authority.
INVALID_PROVIDER_RESPONSE	Empty content, malformed JSON, extra top-level fields, missing command name, missing args object, or more than 100 commands.	No	Tighten the prompt or use text mode. No command is executed.
PROVIDER_TIMEOUT	Completion exceeded timeoutSeconds.	Yes	Check provider health and reconcile provider usage before retrying.
EXECUTION_INTERRUPTED	The workflow thread was interrupted.	Yes	Inspect workflow cancellation or shutdown state.
PROVIDER_ERROR	Adapter, network, authentication, rate-limit, or provider failure.	Usually	Inspect provider status and the sanitized error. Avoid blind retries after ambiguous billing.

Example

Input:

{
  "prompt": "Propose one command that creates a launch checklist.",
  "responseMode": "json_commands"
}

Expected provider content and normalized result:

{
  "status": "success",
  "provider": "OPENAI",
  "model": "approved-model-id",
  "attempts": 1,
  "content": "{\"commands\":[{\"name\":\"createChecklist\",\"args\":{\"title\":\"Launch\"}}]}",
  "commands": [
    {
      "name": "createChecklist",
      "args": {"title": "Launch"}
    }
  ]
}

The next workflow step must authorize and validate createChecklist before dispatching it.

Notes

• Pagination: not applicable; one execution produces one completion.
• Limits: the module accepts at most 100 structured commands and bounds error text to 1,000 characters. Provider token and content limits are model-specific.
• Idempotency: completions are not idempotent, even at temperature zero. A retry can consume additional credits and return different content.
• Rate limits: provider errors are surfaced but the module does not automatically retry. Workflow policy should apply bounded backoff only after reconciling ambiguous attempts.
• API constraints: OpenAI uses the shared adapter and IntegrationAccount credential; Ollama uses the configured compatible endpoint. Other providers fail closed instead of being silently routed through an incompatible transport.
• Secrets: credentials are never logged or returned. Provider error messages pass through the shared workflow redaction policy.
• Observability: logs contain provider, model, response mode, command count, and safe error code, never prompt or completion content.
• Destructive behavior: this module cannot execute tools or commands. Any downstream dispatcher owns authorization, approval, idempotency, audit, and compensation.
• Unverified boundary: deterministic tests validate request construction, account resolution, output mapping, strict parsing, and redaction. Live provider behavior requires a separately authorized account and is not exercised by the repository test suite.