Enhanced Material Expert

This document provides detailed information about the Enhanced Material Expert, a specialized crewAI agent that extends the basic Material Expert with comprehensive metadata formatting capabilities.

Overview

The Enhanced Material Expert builds upon the standard Material Expert by ensuring all material-related responses include comprehensive, well-structured metadata. It enhances the user experience by consistently providing rich, detailed information about materials, including technical specifications, available options, and manufacturer details in a standardized format.

Key Capabilities

The Enhanced Material Expert offers all the capabilities of the standard Material Expert, plus these enhanced features:

Comprehensive Metadata Presentation
- Present complete material specifications in every response
- Structure information consistently for better readability
- Include technical details that might otherwise be omitted
- Ensure all material properties are presented
Structured Response Formatting
- Convert raw material data into well-organized descriptions
- Format search results with standardized property sections
- Transform JSON data into readable, comprehensive text
- Maintain consistent information hierarchy
Complete Material Specifications
- Always include available colors, sizes, and finishes
- Provide comprehensive technical specifications
- Include manufacturer information when available
- Detail installation requirements and considerations
Enhanced Material Comparisons
- Present side-by-side comparisons with complete metadata
- Highlight differences with consistent property references
- Ensure no critical specification is omitted in comparisons
- Maintain metadata consistency across multiple materials
Metadata-Aware Recommendations
- Base recommendations on complete technical information
- Reference specific properties when suggesting applications
- Include relevant metadata in application guidance
- Ensure recommendations are backed by detailed specifications

Architecture

The Enhanced Material Expert integrates with the broader KAI platform through the same components as the standard Material Expert:

Component Structure

packages/
├── agents/
│   ├── src/
│   │   ├── frontend/
│   │   │   ├── materialExpert.ts             # Base agent
│   │   │   └── enhancedMaterialExpert.ts     # Enhanced agent implementation
│   │   ├── services/
│   │   │   └── serviceFactory.ts             # Service creation system
│   │   ├── tools/
│   │   │   ├── materialSearch.ts             # Material search tool
│   │   │   ├── vectorSearch.ts               # Vector search tool
│   │   │   └── index.ts                      # Tool exports
│   │   ├── utils/
│   │   │   └── materialMetadataFormatter.ts  # Metadata formatting utilities
│   │   └── core/
│   │       └── types.ts                      # Agent type definitions
└── client/
    └── src/
        └── components/
            └── agents/
                ├── MaterialExpertPanel.tsx   # Client-side interface
                └── AgentDashboard.tsx        # Agent integration in UI

Architectural Layers

Agent Layer (enhancedMaterialExpert.ts)
- Extends the base Material Expert functionality
- Processes and enhances agent responses with metadata
- Implements JSON detection and formatting
- Provides enhanced instructions to the LLM
Formatter Layer (materialMetadataFormatter.ts)
- Provides specialized formatting functions
- Transforms raw material data into structured descriptions
- Formats search results consistently
- Generates comprehensive material descriptions
Service & Tool Layers
- Use the same services and tools as the Material Expert
- Access material database and search capabilities
- Retrieve comprehensive material information
- Support vector-based similarity searches
UI Layer (MaterialExpertPanel.tsx)
- Presents the enhanced material information in the UI
- Displays comprehensive metadata in a readable format
- Maintains the same interface as the standard Material Expert
- Benefits from enriched agent responses

Implementation Details

Agent Implementation

The Enhanced Material Expert extends the MaterialExpert implementation with response enhancement capabilities:

export class EnhancedMaterialExpert implements UserFacingAgent {
  // Standard UserFacingAgent properties
  public id: string;
  public type: AgentType;
  public name: string;
  public description: string;
  public agent: Agent;
  public config: AgentConfig;

  // Enhanced method with metadata formatting
  public async processUserInput(message: string): Promise<string>;
  
  // Private helper method for metadata enhancement
  private enhanceResponseWithMetadata(response: string, originalQuery: string): string;
}

Response Enhancement

The Enhanced Material Expert processes responses to ensure comprehensive metadata:

private enhanceResponseWithMetadata(response: string, originalQuery: string): string {
  try {
    logger.debug('Enhancing response with comprehensive material metadata');
    
    // Check if the response contains JSON data (material search results)
    if (response.includes('"id":') && response.includes('"name":')) {
      try {
        // Try to parse JSON data in the response
        const jsonMatch = response.match(/\{[\s\S]*\}/);
        if (jsonMatch) {
          const jsonData = JSON.parse(jsonMatch[0]);
          
          // Format material results if they exist
          if (jsonData.results && Array.isArray(jsonData.results)) {
            const formattedMaterials = formatMaterialSearchResults(jsonData.results);
            
            // Generate detailed descriptions for each material
            const materialDescriptions = formattedMaterials.map(material => 
              generateMaterialDescription(material)
            );
            
            // Replace the JSON data with formatted material descriptions
            return response.replace(
              jsonMatch[0], 
              `Here are the materials that match your query:\n\n${materialDescriptions.join('\n\n---\n\n')}`
            );
          }
          
          // Handle single material case
          if (jsonData.id && jsonData.name) {
            const formattedMaterial = formatMaterialMetadata(jsonData);
            const materialDescription = generateMaterialDescription(formattedMaterial);
            
            // Replace the JSON data with formatted material description
            return response.replace(jsonMatch[0], materialDescription);
          }
        }
      } catch (error) {
        // Continue with the original response if JSON parsing fails
      }
    }
    
    // If no JSON data found, return the original response
    return response;
  } catch (error) {
    return response; // Return original response on error
  }
}

Explicit Material Metadata Instructions

The Enhanced Material Expert includes detailed instructions for the LLM:

const materialMetadataInstructions = `
IMPORTANT: When discussing materials, ALWAYS include comprehensive details about:
- What the material is (e.g., tile, wood, lighting)
- The specific name of the material (e.g., Blanco Beige, Nordic Oak)
- Available colors
- Available sizes/dimensions
- Finish options
- Technical specifications
- Manufacturer information

For example, instead of just saying "This tile would work well for your bathroom floor",
provide detailed information like: "Blanco Beige is a porcelain tile manufactured by 
CeramicWorks. It comes in White and Cream colors, available in sizes 12"x24", 24"x24", 
and 24"x48". It has a matte finish with R10 slip resistance rating, making it suitable 
for bathroom floors."

Always present material information in a clear, structured format that highlights
the key metadata properties available in our database.
`;

Setup Instructions

Prerequisites

Functioning KAI platform with material database
CrewAI integration set up according to CrewAI installation guide
Vector search capabilities for material similarity

Installation

The Enhanced Material Expert is included in the standard crewAI integration package:

# Navigate to the agents directory
cd packages/agents

# Install dependencies if not already done
yarn install

Configuration

Configure the agent in your application initialization:

import  from '@kai/agents';

// Create an Enhanced Material Expert instance
const enhancedMaterialExpert = await createEnhancedMaterialExpert(
  {
    id: 'enhanced-material-expert-1',
    name: 'Material Expert',
    description: 'Expert in construction materials with comprehensive metadata',
    verbose: true,
    // Additional configuration options
  },
  {
    model: 'gpt-4',
    temperature: 0.3
  }
);

Usage Examples

Client-Side Integration

import React from 'react';
import  from '../components/agents/MaterialExpertPanel';

const MaterialExpertPage: React.FC = () => {
  return (
    <div className="material-expert-page">
      <h1>Material Expert</h1>
      {/* Use the Panel with enhanced agent type */}
      <MaterialExpertPanel useEnhancedExpert= />
    </div>
  );
};

export default MaterialExpertPage;

Processing User Queries

import  from '@kai/agents';

// Create the Enhanced Material Expert
const enhancedMaterialExpert = await createEnhancedMaterialExpert(
  ,
  
);

// Ask questions about materials with enhanced responses
const query1 = 'What materials would work best for a kitchen backsplash?';
const response1 = await enhancedMaterialExpert.processUserInput(query1);
console.log(response1); // Response includes comprehensive metadata

const query2 = 'Compare ceramic and porcelain tiles for bathroom floors.';
const response2 = await enhancedMaterialExpert.processUserInput(query2);
console.log(response2); // Comparison includes complete specifications

const query3 = 'What are the technical specifications of Carrara marble?';
const response3 = await enhancedMaterialExpert.processUserInput(query3);
console.log(response3); // Full technical specifications included

Enhanced Response Examples

Standard Material Expert Response:

Ceramic tiles would work well for your bathroom floor. They are durable, water-resistant,
and come in many designs. They're also less expensive than porcelain.