contaigents/CONVERSATION_ARCHITECTURE_EXAMPLES.md

Modular AI Content Ecosystem with Audio Generation

# Conversation Architecture Examples

## Current vs New Message Handling

### Current Problematic Approach

#### Single Concatenated Prompt (All Providers)
```typescript
// ❌ Current implementation - everything as one user message
const context = [
  `System: You are a helpful AI assistant with access to file operations.`,
  `\n\n## Current Project Structure\n📁 cli/\n  🔷 src/\n    📝 README.md`,
  `\n\n## Available Tools\nYou have access to read_file, write_file tools...`,
  `\n\nConversation History:`,
  `Human: Can you read the README file?`,
  `Assistant: I'll read the README file for you.`,
  `<tool_call name="read_file" id="1"><file_path>README.md</file_path></tool_call>`,
  `<tool_response id="1">...file content...</tool_response>`,
  `Here's the content of the README file...`,
  `\n\nHuman: Now create a summary file`,
  `\n\nAssistant:`
].join('');

// Sent to ALL providers as single user message
const response = await provider.executePrompt(context);
```

**Problems:**
- Loses conversation structure for conversation-capable providers
- Tool responses mixed with conversation flow
- No role separation
- Inefficient context usage
- Poor conversation quality

### New Hybrid Approach

#### For Conversation-Capable Providers (OpenAI, Anthropic, DeepSeek, OpenRouter)

```typescript
// ✅ Proper conversation structure
const messages = [
  {
    role: "system",
    content: `You are a helpful AI assistant with access to file operations.

## Current Project Structure
📁 cli/
  🔷 src/
    📝 README.md

## Available Tools
You have access to the following tools. To use a tool, include a tool call in your response using XML format:

<tool_call name="tool_name" id="1">
  <parameter_name>parameter_value</parameter_name>
</tool_call>`
  },
  {
    role: "user",
    content: "Can you read the README file?"
  },
  {
    role: "assistant", 
    content: `I'll read the README file for you.

<tool_call name="read_file" id="1">
  <file_path>README.md</file_path>
</tool_call>`
  },
  {
    role: "user",
    content: `<tool_response id="1">
  <tool_call name="read_file">
    <file_path>README.md</file_path>
  </tool_call>
  <result>
    <content>
# Project Title
This is the project README content...
    </content>
  </result>
</tool_response>`,
    metadata: { internal: true, isToolResponse: true }
  },
  {
    role: "assistant",
    content: "Here's the content of the README file:\n\n# Project Title\nThis is the project README content..."
  },
  {
    role: "user",
    content: "Now create a summary file"
  }
];

const response = await provider.executeConversation(messages);
```

#### For Simple Prompt Providers (HuggingFace, Ollama, Replicate)

```typescript
// ✅ Optimized prompt string for simple providers
const prompt = `System: You are a helpful AI assistant with access to file operations.

## Current Project Structure
📁 cli/
  🔷 src/
    📝 README.md

## Available Tools
You have access to read_file, write_file tools...

Conversation History:
user: Can you read the README file?
assistant: I'll read the README file for you.

<tool_call name="read_file" id="1">
  <file_path>README.md</file_path>
</tool_call>

Tool Results:
<tool_response id="1">
  <tool_call name="read_file">
    <file_path>README.md</file_path>
  </tool_call>
  <result>
    <content>
# Project Title
This is the project README content...
    </content>
  </result>
</tool_response>

assistant: Here's the content of the README file:

# Project Title
This is the project README content...