Tool Chains & Workflows

Relevant source files

The following files were used as context for generating this wiki page:

• lib/chat/toolChains/toolChains.ts
• lib/chat/toolChains/createNewArtistToolChain.ts
• lib/chat/toolChains/create_release_report/createReleaseReportToolChain.ts
• lib/chat/toolChains/index.ts
• lib/chat/toolChains/tests/toolChains.test.ts
• lib/chat/toolChains/tests/getPrepareStepResult.test.ts

Tool Chains and Workflows represent a structured sequence of AI tool executions designed to automate complex music industry tasks, such as onboarding new artists or generating comprehensive release reports. Instead of relying on a single large-language model (LLM) call to manage an entire process, the system breaks down high-level objectives into discrete, enforceable steps that leverage specialized tools and specific models for optimal performance.

This architecture allows the AI to follow a "Sandbox-First" approach, where the assistant can perform deep research, manage files via Arweave, and update artist accounts in a deterministic order while maintaining the flexibility to use specific models for specific tasks.
Sources: lib/chat/toolChains/toolChains.ts:24-30, lib/chat/const.ts:7-15

System Architecture

The workflow system is built on three primary components: the Tool Chain Definitions, the Execution Sequence, and the Model Mapping.

Tool Chain Definition

A tool chain is defined as an array of ToolChainItem objects. Each item specifies the toolName to be called and can optionally override the system prompt or provide specific messages for that particular step in the workflow.
Sources: lib/chat/toolChains/toolChains.ts:5-9, lib/chat/toolChains/tests/toolChains.test.ts:7-16

Data Structures

Type	Field	Description
ToolChainItem	toolName	The unique identifier of the MCP or internal tool to execute.
	system	Optional system prompt override for this specific step.
	messages	Optional array of model messages to append for this step.
PrepareStepResult	toolChoice	Forces the LLM to use a specific tool.
	model	Specific model assigned to this step (e.g., gemini-2.5-pro).
	system	The system prompt to use for the LLM call.

Sources: lib/chat/toolChains/toolChains.ts:5-18, lib/chat/toolChains/tests/toolChains.test.ts:24-43

Execution Logic and Model Selection

Workflows are triggered by specific tool calls. Once a "trigger tool" is identified in the chat history, the system calculates the next tool in the sequence based on the getExecutedToolTimeline.

Model Mapping

Certain tools are mapped to specific models via the TOOL_MODEL_MAP. This ensures that sensitive operations, like updating database records via update_account_info, are handled by high-reliability models.

• update_account_info: Mapped to gemini-2.5-pro
  Sources: lib/chat/toolChains/toolChains.ts:14-18, lib/chat/toolChains/tests/toolChains.test.ts:133-145

Major Workflows

The repository implements several pre-defined workflows to handle complex business processes.

1. New Artist Onboarding (create_new_artist)

This workflow automates the creation of an artist profile by searching Spotify, researching the artist across the web, generating a knowledge base report, and uploading it to Arweave.

2. Release Report Generation (create_release_report)

Focuses on gathering data for specific music releases to create a formatted report for stakeholders.

1. Research: Uses web_deep_research to find streaming data, TikTok trends, and chart positions.
2. Knowledge Base: Creates a structured knowledge base via create_knowledge_base.
3. Document Creation: Formats results into a TXT file using generate_txt_file with a strict system prompt to avoid hallucinations.
4. Distribution: Attaches the report to the artist account and executes send_email.
   Sources: lib/chat/toolChains/create_release_report/createReleaseReportToolChain.ts:4-35, lib/chat/toolChains/tests/toolChains.test.ts:121-131

Integration with Data Sources

Workflows often rely on aggregating content from various "knowledge" entries. The system uses utility functions like getKnowledgeBaseText to filter and fetch content from URLs (like Arweave) before processing.

Supported MIME Types	Processing Action
text/plain	Fetched and included in context
text/markdown	Fetched and included in context
application/json	Fetched and included in context
image/*, application/pdf	Filtered out from text processing

Sources: lib/files/tests/getKnowledgeBaseText.test.ts:44-90

Conclusion

Tool Chains and Workflows provide a deterministic backbone for the AI assistant, ensuring that complex tasks are executed in a reliable order. By mapping specific steps to specialized models and enforcing sequences through a triggered timeline, the system maintains high technical accuracy while leveraging external tools for deep research and decentralized storage.