sciagent/be0/CHAT_ASSISTANT_README.md

# Chat Assistant Module

## Overview

The Chat Assistant module provides a conversational AI interface for answering policy and compliance questions using Ollama.

## Architecture

### Backend (`be0/src/chat_assistant.py`)

The `ChatAssistant` class provides:
- **Chat functionality**: Conversational AI for policy questions
- **Content verification**: Verify content against compliance requirements
- **Policy Q&A**: Answer questions about policies and compliance

### Frontend (`fe0/src/features/chat/`)

The frontend chat feature includes:
- **Service layer**: API communication with backend
- **React hooks**: Easy-to-use hooks for chat functionality
- **Type definitions**: TypeScript types for type safety

## API Endpoints

### 1. Chat Endpoint
```
POST /api/v1/chat
```

**Request Body:**
```json
{
  "message": "What are ISO 27001 requirements?",
  "conversation_history": [
    {
      "role": "user",
      "content": "Previous message"
    },
    {
      "role": "assistant",
      "content": "Previous response"
    }
  ],
  "context": "Optional context about policies"
}
```

**Response:**
```json
{
  "message": "ISO 27001 is an information security management system...",
  "model": "gemma3:27b",
  "tokens_used": 150
}
```

### 2. Verify Content Endpoint
```
POST /api/v1/chat/verify
```

**Form Data:**
- `field_name`: Name of the field being verified
- `content`: Content to verify
- `verification_criteria`: (Optional) Specific criteria to check

**Response:**
```json
{
  "message": "The content meets compliance requirements...",
  "model": "gemma3:27b",
  "tokens_used": 200
}
```

### 3. Policy Question Endpoint
```
POST /api/v1/chat/question
```

**Form Data:**
- `question`: The user's question
- `policy_context`: (Optional) Context about specific policies

**Response:**
```json
{
  "message": "Answer to the policy question...",
  "model": "gemma3:27b",
  "tokens_used": 180
}
```

## Features

### 1. Conversational Context
- Maintains conversation history for context-aware responses
- Keeps last 10 messages for context
- System prompt guides the assistant's behavior

### 2. Policy Expertise
- Specialized in IT governance and compliance
- Knowledgeable about ISO 27001, NIST, GDPR, etc.
- Provides accurate, actionable advice

### 3. Content Verification
- Analyzes content against compliance requirements
- Provides detailed feedback
- Suggests improvements

## Usage

### Backend

```python
from src.chat_assistant import get_chat_assistant

# Get chat assistant instance
assistant = get_chat_assistant()

# Chat
request = ChatRequest(
    message="What is ISO 27001?",
    context="IT governance"
)
response = await assistant.chat(request)

# Verify content
response = await assistant.verify_content(
    field_name="Project Description",
    content="Our project implements security controls..."
)
```

### Frontend

```typescript
import { useChat } from '@/features/chat/hooks/useChat';

const { sendMessage, verifyContent, isLoading } = useChat();

// Send a message
const response = await sendMessage(
  "What are compliance requirements?",
  conversationHistory, // Optional
  "ISO 27001 context"   // Optional
);

// Verify content
const verification = await verifyContent(
  "Project Name",
  "Project content to verify"
);
```

## Configuration

### Model Selection

The default model is `gemma3:27b`. To change it:

```python
# In chat_assistant.py
assistant = ChatAssistant(model_name="your-model-name")
```

### System Prompt

The system prompt can be customized in the `ChatAssistant.__init__` method to change the assistant's behavior and expertise.

## Logging

All chat interactions are logged to:
- `be0/logs/ChatAssistant.log`

This helps with debugging and monitoring.

## Error Handling

The module includes comprehensive error handling:
- Catches and logs all exceptions
- Returns user-friendly error messages
- Raises HTTPException for API errors

## Testing

To test the chat assistant:

1. **Start the backend:**
   ```bash
   cd be0
   docker-compose up be0
   ```

2. **Test via API:**
   ```bash
   curl -X POST http://localhost:4402/api/v1/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "What is ISO 27001?"}'
   ```

3. **Test via Frontend:**
   - Open the Dashboard
   - Use the ChatAssistant component
   - Ask questions or verify content

## Integration

The ChatAssistant is integrated with:
- **ChatAssistant.tsx**: React component in the Dashboard
- **useChat hook**: React hook for chat functionality
- **chatService**: API service layer

## Future Enhancements

Potential improvements:
1. Streaming responses for real-time text generation
2. Multi-turn conversation management
3. Document context injection
4. Voice input/output
5. Response rating and feedback
6. Conversation export
7. Custom model fine-tuning