Feature/be 018 ai assistant

docs/AI_ARCHITECTURE.md

@@ -0,0 +1,21 @@
+# AI Architecture
+
+## Overview
+The AI Assistant Backend API serves as the orchestration layer between TruthBounty's verified protocol data and external language models (LLMs). It centralizes prompt management, RAG (Retrieval-Augmented Generation), and usage tracking.
+
+## Components
+1. **Conversation Management**: Handles storing and retrieving conversation history. Ensure continuity across sessions.
+2. **RAG Service**: Retrieves context from verified sources (e.g. database claims, governance proposals, protocol docs).
+3. **LLM Provider**: Abstracted interface to communicate with OpenAI, Anthropic, or future model providers. Configurable via environment variables.
+4. **Security & Validation**: Checks for prompt injections, enforces rate limits, and scopes access to authenticated users.
+5. **Usage Tracking**: Monitors token usage, latency, and provider utilization for analytics.
+
+## Data Flow
+1. User sends message -> API Gateway -> AI Assistant Controller.
+2. AI Assistant Service retrieves conversation history (up to 10 previous messages for short-term memory).
+3. RAG Service retrieves relevant protocol context based on user query.
+4. System prompt, context, and conversation history are combined.
+5. The payload is sent to the LLM Provider Service.
+6. The LLM Provider returns the response, which is saved to the database.
+7. Usage metrics are logged asynchronously.
+8. API response is returned to the client.

docs/PROMPT_ENGINEERING_GUIDE.md

@@ -0,0 +1,22 @@
+# Prompt Engineering Guide
+
+## System Prompt Principles
+The system prompt for TruthBounty's AI Assistant is critical for ensuring the AI is helpful, harmless, and strictly grounded in protocol reality.
+
+### 1. Grounding in Truth
+Always instruct the AI to rely exclusively on the provided context (RAG). Do not let it hallucinate rules or governance mechanics.
+*Example:* "Your answers must be grounded ONLY in verified protocol information. If you do not know the answer based on the provided context, state clearly that you do not know."
+
+### 2. Role Definition
+Define the assistant's persona.
+*Example:* "You are the TruthBounty AI Assistant. You help contributors navigate the protocol, explain proposals, analyze claims, and interpret disputes."
+
+### 3. Safety & Limitations
+Explicitly state what the AI cannot do.
+*Example:* "Do not fabricate protocol state. Do not attempt to execute any privileged operations autonomously. You are a read-only assistant."
+
+## Tool Usage
+When the AI uses tools (e.g. claim lookup), ensure the prompt describes the tool's exact input format and output interpretation.
+
+## RAG Context Formatting
+Provide context in a structured, consistent format (e.g. JSON or Markdown bullet points) so the LLM can easily parse the facts before generating a response.