services/ai

pkgs/gizclaw/services/ai Has configurable AI resources and provider integration in GizClaw, including credential, model, voice, workflow and workspace. It organizes these resources into product capabilities that can be consumed by the Agent Runtime, but is not responsible for the online life cycle of the Agent instance.

Directory structure

services/ai/
├── credential/        # Provider credential resources
├── model/             # Model resources and GenX model resolution
├── openaiapi/         # OpenAI-compatible product service
├── peergenx/          # Peer-backed GenX provider integration
├── providertenants/   # Provider tenant resources and provider-specific configuration
├── voice/             # Voice resources and provider voice resolution
├── workflow/          # Workflow resources and driver selection
│   └── agents/        # concrete workflow agent integrations
└── workspace/         # Workspace resources, runtime stores, and history

Subdirectory responsibilities

credential

Have the credential resources required to call external AI providers and their persistence boundaries. Credentials are protected product resources and should not leak into workflow definitions, workspace history, or generic GenX abstractions.

model

Owns the GizClaw model catalog and has the ability to parse persistent model definitions into models that GenX can use. The general model interface belongs to pkgs/genx; the specific GizClaw model resources and selection logic belong here.

openaiapi

Implement GizClaw's OpenAI-compatible product service and expose the configured Agent/GenX capabilities to the corresponding HTTP surface. The OpenAPI contract belongs to api/, and the route assembly belongs to the root pkgs/gizclaw, which contains the AI ​​business behavior of the surface.

peergenx

Connect GizClaw peer or provider-backed generation capabilities to the unified GenX abstraction. Provider SDK integration and provider-specific resolution stay here and should not go into generic pkgs/genx.

providertenants

Have product resources for each AI provider tenant, such as provider endpoint, account-level configuration, and information required for voice synchronization. It can rely on specific provider SDKs, but it cannot allow provider-specific fields to proliferate into unrelated areas.

voice

Have voice resources and provider voice mappings available to Agent/GenX for selection. Common capabilities such as Audio codec, resampling and playback belong to pkgs/audio and do not belong to the voice catalog.

workflow

Owns workflow definition, driver selection, and workflow resource persistence. workflow/agents Stores integration between specific workflow engines and GizClaw Agent Host, such as Flowcraft, chatroom, AST translation and realtime workflow.

Workflow describes how to run an Agent, but does not own the online state and stream lifecycle of the Agent instance.

Flowcraft history

The Server optionally resolves the reserved named log store flowcraft-history and injects it into both normal and pet Flowcraft agents. The store must implement logstore.MutableStore; configuring an immutable driver such as Volc TLS is a startup error. Without that named store, Flowcraft keeps its existing workspace JSONL history. Existing JSONL files are not migrated, and a configured store error is returned to the caller instead of falling back to the file.

The adapter stores one Stream=flowcraft-history, Kind=message record per message. Indexed attributes contain workspace_name, conversation_id, and schema_version; the complete Flowcraft message, including tool calls, tool results, and data-reference metadata, stays in the JSON payload. Reads use the LogStore query cursor directly. Save replaces existing message records, deletes surplus records, and appends new records; it creates no snapshot, tombstone, operation log, or separate page index.

This is Flowcraft runtime history only. Workspace HistoryStore remains a separate resource boundary, and audio objects continue to use object storage.

workspace

Has workspace resources, workspace runtime storage and history. The Workspace is the persistence boundary for instantiating the Agent environment; the running Agent, input and output, and connection streams are the responsibility of the Runtime domain.

Workspace also owns the immutable system lifecycle classification. Generic creation stores system: false; domain-owned creation stores system: true. Generic deletion rejects system Workspaces, while the internal system lifecycle surface is available only to the owning Social or Gameplay service.

Dependencies and boundaries

Should be placed at services/ai:

• Product resources for AI provider, credential, model, voice, workflow and workspace.
• Provider integration and GizClaw-specific GenX resolution.
• Adaptation of Workflow engine and GizClaw Agent Runtime.

Shouldn't be placed here:

• Generic GenX interface, audio codec or transport.
• Agent instance, peer connection and online operation life cycle.
• Provider credential plain text log or cross-domain replication.
• Wiring codes that belong only to the Admin/Peer HTTP route registration.