refactor: improve terminology consistency and enhance documentation across architecture, implementation, RAG, interface, and demo sections

Author: merendamattia

latex/sections/03_architecture.tex

@@ -7,11 +7,11 @@ \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.\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 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. Chatbot Agent focuses on natural conversation and financial profile extraction, maintaining conversation history and interpreting user intent while guiding users toward providing relevant financial information. Financial Advisor Agent 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 (piano di accumulo) values, performance indicators, and risk assessment. These models are implemented using Pydantic, which enforces type safety at runtime and provides validation.
+The data model layer ensures type safety and clear data contracts throughout the system. Financial Profile 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 (piano di accumulo) values, performance indicators, and risk assessment. These models are implemented using Pydantic, which enforces type safety at runtime and provides validation.
 
-The retrieval layer implements retrieval-augmented generation specifically for financial data. RAGAssetRetriever maintains a vector database of historical ETF and stock data, supports semantic search for relevant financial assets, integrates historical price data spanning ten years, and provides structured asset information for recommendations. This component is essential for grounding LLM recommendations in factual, historical information rather than allowing the model to generate potentially inaccurate figures.
+The retrieval layer implements retrieval-augmented generation specifically for financial data. RAG Asset Retriever maintains a vector database of historical ETF and stock data, supports semantic search for relevant financial assets, integrates historical price data spanning ten years, and provides structured asset information for recommendations. This component is essential for grounding LLM recommendations in factual, historical information rather than allowing the model to generate potentially inaccurate figures.
 
 The tool layer provides specialized computation capabilities that agents can invoke. Currently, the system includes financial analysis tools for computing financial metrics, historical returns, and risk indicators. Portfolio validation tools verify portfolio structure and compliance with constraints. Future extensions might include tax optimization tools, rebalancing advisors, and risk simulation engines.
 
@@ -23,7 +23,7 @@ \subsection{Multi-Provider LLM Support}
 
 \subsection{Data-Flow}
 
-The typical interaction flow through the system follows a well-defined sequence. A user initiates conversation with ChatbotAgent, which engages the user in dialogue to gather financial information. The user provides profile details and financial goals through natural conversation. FinancialAdvisorAgent then extracts a structured FinancialProfile from the conversation history using the LLM with structured output capabilities. The agent queries RAGAssetRetriever for suitable assets based on the user's profile constraints. The portfolio generation logic combines user preferences with historical data to create a diversified portfolio. The system presents recommendations to the user with comprehensive analysis including historical performance, risk metrics, and diversification ratios. The user can refine preferences and iterate through the analysis cycle, with the agent updating recommendations based on new information.
+The typical interaction flow through the system follows a well-defined sequence. A user initiates conversation with Chatbot Agent, which engages the user in dialogue to gather financial information. The user provides profile details and financial goals through natural conversation. Financial Advisor Agent then extracts a structured Financial Profile from the conversation history using the LLM with structured output capabilities. The agent queries RAG Asset Retriever for suitable assets based on the user's profile constraints. The portfolio generation logic combines user preferences with historical data to create a diversified portfolio. The system presents recommendations to the user with comprehensive analysis including historical performance, risk metrics, and diversification ratios. The user can refine preferences and iterate through the analysis cycle, with the agent updating recommendations based on new information.
 
 \begin{figure}[h]
 \centering

latex/sections/04_implementation.tex

@@ -5,7 +5,7 @@ \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, 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.
+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 Financial Profile, 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.
 
 The data processing layer relies on Pandas for tabular data manipulation and financial time-series analysis, NumPy for numerical computations and matrix operations, and scikit-learn for statistical analysis and machine learning utilities.
 
@@ -17,7 +17,7 @@ \subsection{Agent Implementation}
 
 \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.
+Pydantic models ensure data integrity throughout the system. Financial Profile 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{DevOps and Continuous Integration}