docs: implement ChatAgent documentation and reasoning flow

app/src/agents/docs/agents/chat-agent.md

@@ -0,0 +1,66 @@
+# ChatAgent 
+
+The **ChatAgent** is the default specialized agent within the Perry ecosystem. Its primary responsibility is to handle general interactions, "chitchat," and professional greetings that do not require specific Odoo module actions (like Finance or CRM).
+
+## Overview
+
+Unlike other agents, the `ChatAgent` does not execute Odoo tools. Instead, it focuses on maintaining Perry's **strict professional persona** while ensuring that every response is structured as valid JSON for system consistency.
+
+### Key responsibilities:
+*   **Chitchat handling**: Responding to "Hello," "How are you?", or general AI queries.
+*   **Persona enforcement**: Ensuring Perry remains formal, direct, and humorless.
+*   **JSON enforcement**: Guaranteeing that all outputs follow the `{ "reply_content": "..." }` schema.
+
+## Technical logic
+
+### 1. Persona and system prompt
+The agent is initialized with a strict system instruction set:
+*   **Role**: Artificial Intelligence Assistant for Odoo.
+*   **Tone**: Strictly professional and formal.
+*   **Constraint**: No informal language, no humor, and **JSON-only** output.
+
+### 2. Reasoning process (PerryThought)
+The `ChatAgent` implements a transparent reasoning flow by yielding `PerryThought` objects during its execution. This allows the user to see exactly what Perry is doing in the background:
+
+| Step ID | Reasoning Description |
+| :--- | :--- |
+| `history_parsing` | Analyzes conversation history and chitchat context. |
+| `llm_query` | Consults the LLM using Perry's professional communication model. |
+| `json_parsing` | Extracts and parses the JSON from the model's raw text. |
+| `validation` | Verifies the response integrity against professional standards. |
+| `conclusion` | Finalizes the communication and generates the outgoing message. |
+
+## Data models
+
+### ChatAction
+The agent uses a Pydantic model to validate the LLM's output before sending it to the user.
+
+```python
+class ChatAction(BaseModel):
+    reply_content: Optional[str] = Field(
+        default="I will process your request accordingly."
+    )
+```
+
+## Execution flow (`act` method)
+
+1.  **Memory C¡check**: Verifies that there is message history. If empty, it yields a `Failed` state.
+2.  **LLM interaction**: Sends the last user message to the model (OpenAI/Gemini/vLLM).
+3.  **Advanced parsing**:
+    *   Attempts to parse direct JSON.
+    *   Uses **Regex** to extract JSON if the model wraps it in an `AgentRunResult` object.
+    *   Cleans Markdown code blocks (`` ```json ``).
+    *   **Fallback**: If `json.loads` fails, it attempts `ast.literal_eval` for maximum robustness.
+4.  **Validation**: Validates the dictionary against the `ChatAction` model.
+5.  **Output**: Yields the final `Message` to the orchestrator.
+
+## Observability (Logfire)
+
+The `ChatAgent` is fully instrumented with **Logfire** for real-time tracing:
+*   **Spans**: Every reasoning step is wrapped in a Logfire span.
+*   **Metadata**: Logs include `agent_name`, `sender`, `receiver`, and `message_length`.
+*   **Error Handling**: Failed parsing or validation attempts are logged as exceptions with full raw response data for debugging.
+
+## Example Interaction
+
+![Example interaction](../imgs/chat_agent_ex.png)