fix: enhance documentation in architecture, implementation, and interface sections

Author: merendamattia

latex/sections/03_architecture.tex

@@ -7,7 +7,7 @@ \subsection{High-Level Overview}
 
 \subsection{Core Components}
 
-The system is composed of several interrelated components that work together to deliver financial advisory services. The agent layer contains specialized AI agents built on top of the datapizza-ai framework. BaseAgent serves as an abstract foundation that encapsulates common agent functionality including initialization, configuration loading, system prompt management, and tool registration. All specialized agents inherit from BaseAgent to ensure consistency and reduce code duplication. ChatbotAgent focuses on natural conversation and financial profile extraction, maintaining conversation history and interpreting user intent while guiding users toward providing relevant financial information. FinancialAdvisorAgent specializes in portfolio generation and analysis, utilizing RAG to access historical financial data and providing evidence-based recommendations.
+The system is composed of several interrelated components that work together to deliver financial advisory services. The agent layer contains specialized AI agents built on top of the datapizza-ai framework.\footnote{\url{https://github.com/datapizza-labs/datapizza-ai}.} BaseAgent serves as an abstract foundation that encapsulates common agent functionality including initialization, configuration loading, system prompt management, and tool registration. All specialized agents inherit from BaseAgent to ensure consistency and reduce code duplication. ChatbotAgent focuses on natural conversation and financial profile extraction, maintaining conversation history and interpreting user intent while guiding users toward providing relevant financial information. FinancialAdvisorAgent specializes in portfolio generation and analysis, utilizing RAG to access historical financial data and providing evidence-based recommendations.
 
 The data model layer ensures type safety and clear data contracts throughout the system. FinancialProfile captures demographic and financial characteristics including age, employment status, income, expenses, debt, savings, investment experience, risk tolerance, and financial goals. Portfolio represents investment recommendations including asset allocations, expected returns, volatility metrics, and diversification ratios. PACMetrics encodes portfolio analysis metrics including PAC (patrimonio atteso) values, performance indicators, and risk assessment. These models are implemented using Pydantic, which enforces type safety at runtime and provides validation.
 
@@ -19,7 +19,7 @@ \subsection{Multi-Provider LLM Support}
 
 A critical design feature is the abstraction of LLM provider complexity through a unified provider layer. This enables users to select their preferred provider based on individual needs and constraints.
 
-Ollama provides full offline inference with no data sent to external servers, making it ideal for privacy-sensitive applications. However, it requires local model download and provides variable performance depending on hardware capabilities. Google Gemini offers cloud-based API access with advanced reasoning capabilities and integration with the Google ecosystem, but requires API key authentication and incurs usage costs. OpenAI provides industry-standard LLM capabilities with the highest quality responses and fine-grained API control, but requires API key and billing setup with associated costs. The client abstraction layer in the codebase (`src/clients.py`) provides a unified interface for all providers, allowing seamless switching at configuration time without modifying application logic.
+Ollama provides full offline inference with no data sent to external servers, making it ideal for privacy-sensitive applications. However, it requires local model download and provides variable performance depending on hardware capabilities. Google Gemini offers cloud-based API access with advanced reasoning capabilities and integration with the Google ecosystem, but requires API key authentication and incurs usage costs. OpenAI provides industry-standard LLM capabilities with the highest quality responses and fine-grained API control, but requires API key and billing setup with associated costs. The client abstraction layer in the codebase provides a unified interface for all providers, allowing seamless switching at configuration time without modifying application logic.
 
 \subsection{Data-Flow}
 

latex/sections/04_implementation.tex

@@ -3,7 +3,7 @@ \section{Technical Implementation}
 
 \subsection{Technology Stack}
 
-The implementation leverages a carefully selected technology stack optimized for AI, data processing, and web deployment. The core framework is datapizza-ai,\footnote{\url{https://github.com/datapizza-labs/datapizza-ai}} a modern italian AI framework specifically designed for building conversational agents with complex orchestration requirements. The datapizza-ai framework provides comprehensive abstractions for agent lifecycle management, message routing, and tool invocation. It abstracts away the complexities of different LLM provider APIs and authentication mechanisms, allowing the system to seamlessly switch between Ollama for local inference, Google Gemini for cloud-based capabilities, or OpenAI's models, without requiring changes to the agent implementation. The framework manages conversation context and memory through a unified interface, handling both immediate conversation history for contextual understanding and persistent memory for long-term user profile management. Additionally, datapizza-ai provides sophisticated tool management capabilities that enable agents to register and invoke external functions as part of their decision-making process, facilitating integration with specialized services like the RAG retriever.
+The implementation leverages a carefully selected technology stack optimized for AI, data processing, and web deployment. The core framework is datapizza-ai, a modern italian AI framework specifically designed for building conversational agents with complex orchestration requirements. The datapizza-ai framework provides comprehensive abstractions for agent lifecycle management, message routing, and tool invocation. It abstracts away the complexities of different LLM provider APIs and authentication mechanisms, allowing the system to seamlessly switch between Ollama for local inference, Google Gemini for cloud-based capabilities, or OpenAI's models, without requiring changes to the agent implementation. The framework manages conversation context and memory through a unified interface, handling both immediate conversation history for contextual understanding and persistent memory for long-term user profile management. Additionally, datapizza-ai provides sophisticated tool management capabilities that enable agents to register and invoke external functions as part of their decision-making process, facilitating integration with specialized services like the RAG retriever.
 
 The web framework is Streamlit, a Python-based framework enabling rapid development of data applications without requiring JavaScript expertise. Streamlit handles reactive UI updates and state management automatically, greatly reducing development overhead. Pydantic provides runtime type validation and serialization for data models, used extensively for FinancialProfile, Portfolio, and related models, ensuring data consistency throughout the system. Qdrant serves as a vector database engine for semantic search over financial documents and embeddings. Plotly enables interactive, publication-quality financial visualizations including candlestick charts, return distributions, and allocation pie charts.
 
@@ -13,22 +13,12 @@ \subsection{Technology Stack}
 
 \subsection{Agent Implementation}
 
-The agent architecture is built on the datapizza-ai framework, which provides a flexible agent abstraction layer for building intelligent conversational systems. The architecture follows a layered approach where base agent functionality is defined at the foundational level, handling common concerns like configuration management, initialization of language model clients based on selected providers, loading and customization of system prompts, and registration of available tools. This foundation allows specialized agents to be developed by extending base functionality with domain-specific behavior.
-
-Two specialized agent implementations extend this foundation. The ChatbotAgent provides a pure conversational interface focused on engaging users and gathering information without invoking specialized financial tools. It maintains a sequence of strategically designed questions that are presented progressively throughout the conversation, allowing the system to collect financial preferences, risk profiles, and investment objectives in a natural dialogue flow. The chatbot combines language model responses with guided question management, creating a conversational experience that both answers user queries and systematically gathers the information needed for financial profiling.
-
-Financial-domain agents extend the foundation with specialized capabilities tailored to wealth management and investment advising. These agents are configured with financial-specific system prompts that guide the language model toward appropriate financial reasoning. The agents are trained to recognize when they need to invoke specialized tools, such as structured data extraction from conversation history into financial profiles, synthesis of portfolio recommendations based on user constraints and market data, computation of advanced metrics and performance analytics, and construction of semantic queries for the retrieval-augmented generation system. The agents leverage the language model's capability to produce structured outputs, enabling reliable extraction of complex financial information from unstructured conversations.
-
-A key characteristic of the agent implementation is its ability to manage multi-turn conversations where information is progressively gathered and refined. Through datapizza-ai's memory management capabilities, agents maintain awareness of previous interactions, allowing for contextual understanding and smoother user experiences. The agents orchestrate complex workflows that combine language model reasoning with tool invocation, vector similarity search, and financial calculations in a seamless manner.
+The agent architecture, detailed in Section~\ref{sec:architecture}, is built on the datapizza-ai framework and implements a layered approach with base agent functionality and specialized implementations for both conversational and financial-domain interactions. Agents manage multi-turn conversations with memory management capabilities and orchestrate complex workflows combining language model reasoning with tool invocation and financial calculations.
 
 \subsection{Data Model Validation}
 
 Pydantic models ensure data integrity throughout the system. FinancialProfile enforces type safety for all financial attributes, provides default values for missing information, includes field descriptions for API documentation, and supports optional fields for incomplete data. Similar validation is applied to Portfolio and other data structures. This approach catches data errors early and provides clear error messages when data does not conform to expected schemas.
 
-\subsection{Testing Infrastructure}
-
-The project includes a comprehensive test suite organized by category. Unit tests examine individual components in isolation, including financial profile extraction, portfolio analysis, and asset retrieval. Integration tests verify complete workflows such as RAG retrieval and portfolio generation. Fixture-based testing provides shared test data and configurations across tests. Tests are executed using pytest with the ability to run specific test categories or generate coverage reports.
-
 \subsection{DevOps and Continuous Integration}
 
 The project implements a comprehensive continuous integration and continuous deployment pipeline leveraging GitHub Actions to ensure code quality and reliable releases. The automated testing pipeline executes the full test suite on every push to main branches and on pull requests, validating that changes do not introduce regressions. The test environment is configured with Python 3.11 to match production requirements, and critical API keys are provided through secure secrets management to enable testing of cloud-based LLM providers.