Aza Man: AI-Powered Autonomous Financial Assistant

Figure 1: Aza Man icon

---

Abstract

Aza Man is a multi-agent AI system developed for the Agentic AI Developer Certification Program (AAIDC) 2025, offered by ReadyTensor. It delivers personalized financial management through budget creation, expense tracking, and savings management. Leveraging LangGraph for workflow orchestration, SQLite for state persistence, and a Streamlit interface, Aza Man ensures a robust, secure, and user-friendly experience. Integrated with cost-efficient SOTA models via OpenRouter, Groq, and TogetherAI, it promotes financial literacy in regions like Nigeria, addressing economic challenges with intelligent automation. This publication details Aza Man’s architecture, production enhancements, testing, safety, resilience, and deployment, showcasing its readiness for real-world use.

1. Introduction

Agentic AI systems enable autonomous, goal-driven interactions, surpassing traditional chatbots. Aza Man addresses the need for accessible budgeting tools in economically volatile regions like Nigeria, offering a modular, scalable solution with comprehensive testing, safety guardrails, and a user-friendly interface. Built with LangGraph, SQLite, and Streamlit, Aza Man integrates tool-calling, state persistence, and real-time visualizations to empower users in managing finances. This publication outlines Aza Man’s architecture, production enhancements (testing, safety, resilience, UI, documentation), evaluation, and deployment, demonstrating its alignment with AAIDC2025 requirements.

2. System Design Rationale

Aza Man’s design prioritizes production readiness, focusing on modularity, scalability, security, and resilience. LangGraph orchestrates complex workflows, ensuring efficient task delegation and low latency. SQLite, via SqliteSaver, provides lightweight state persistence. The tool-centric architecture uses LangChain’s .bind_tools for structured financial data updates. Security measures include input validation, output filtering, and error handling. The Streamlit interface abstracts technical complexity with a custom-themed dashboard. A .gitattributes file ensures consistent line endings (*.py text eol=lf), resolving Windows-specific LF to CRLF warnings. These choices make Aza Man robust, maintainable, and ready for real-world deployment.

3. System Architecture

Aza Man is a multi-agent system with a supervisor architecture:

• Supervisor Agent: A LangGraph workflow processes user inputs, invokes tools, and routes tasks, using an LLM with bound tools for precise delegation.
• Tool Nodes:
  • set_username: Personalizes interactions with regex-validated usernames.
  • budget: Allocates budgets based on income and savings goals, using Pydantic validation.
  • log_expenses: Tracks categorized expenses with currency consistency.
  • math_tool: Ensures accurate financial calculations.
• State Manager: A custom State class persists variables in SQLite.
• Conversation Summarizer: Condenses chat history after 10 messages to prevent context overload.
• Prompt System: Dynamically formats prompts with user state, enforcing tool usage and scope limits.
• Frontend: A Streamlit interface with login, chat, dashboard (Plotly visualizations), and about pages.

Figure 2: Dashboard page

---

4. Functionality

Aza Man delivers a cohesive financial management experience. Users log in via a regex-validated interface, setting a username with set_username if unset. The budget tool creates budgets from income and savings goals, while log_expenses logs categorized expenses. The math_tool handles all arithmetic, ensuring precision. The State class persists data across sessions, and the summarizer condenses long conversations. The Streamlit frontend provides a chat interface for real-time interaction and a dashboard with Plotly charts visualizing income, expenses, and savings progress. Error messages and guidance enhance usability.

5. Production Enhancements

Aza Man was enhanced to ensure production readiness:

• Testing: A pytest suite with 38 tests (79% coverage) covers unit tests (test_tools.py, 15 tests), integration tests (test_graph.py, 7 tests), and end-to-end UI tests (test_app.py, 6 tests).
• Safety & Security:
  • Input Validation: Regex for usernames, Pydantic for tool inputs.
  • Output Filtering: re.sub removes HTML tags in Streamlit to prevent XSS.
  • Error Handling: Try-except blocks in store_memory and app.py ensure graceful degradation.
  • Logging: User interactions and errors logged in app.py and configuration.py.
• Resilience: A 10-message summarization limit prevents context overload. Retry and timeout logic are planned for LLM calls.

6. Evaluation Methodology

Aza Man was evaluated with:

• Pytest Suite: 38 tests across test_app.py (6), test_configuration.py (5), test_graph.py (7), test_prompts.py (2), test_state.py (3), test_tools.py (15). Coverage: 79% overall, 66% for src/graph.py. All tests pass, with test_store_memory_tool_error fixed to handle Pydantic validation errors.
• OpenEvals: Five test cases in data/finance_eval_results.csv, validating accuracy for budget creation, expense logging, and calculations. All passed.

7. Safety and Security

Aza Man implements robust guardrails:

• Input Validation: Regex ensures valid usernames; Pydantic validates tool inputs.
• Output Filtering: Streamlit uses re.sub to strip HTML tags, preventing XSS attacks.
• Error Handling: Try-except blocks in store_memory and app.py return user-friendly error messages for tool or LLM failures.
• Logging: app.py logs user messages and errors; configuration.py logs prompt formatting issues.
• Future Work: Add dedicated safety tests to validate guardrails.

8. Resilience and Monitoring

Aza Man includes:

• Loop Limits: Summarization after 10 messages prevents context overload.
• Error Handling: Graceful degradation for tool errors and graph streaming failures.
• Logging: Failures logged in app.py for debugging.
• Planned Enhancements: Retry with exponential backoff and timeout handling for LLM calls, with tests to validate resilience.

Figure 3: Test results

---

9. How to Run

1. Clone the Repository:

git clone https://github.com/Blaqadonis/azaman.git
cd azaman

2. Create and Activate a Conda Environment:

conda create -n azaman python=3.11
conda activate azaman

3. Install Dependencies:

pip install -r requirements.txt

4. Create data Directory:

mkdir -p data

5. Set Up Environment Variables:

• Create a .env file:

touch .env

• Add (replace with your API keys):

GROQ_API_KEY=your_groq_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
TOGETHER_API_KEY=your_together_api_key
LANGCHAIN_TRACING_V2=false
LANGCHAIN_API_KEY=your_langchain_api_key
LANGCHAIN_PROJECT=Aza Man_FOR_AAIDC2025

6. Update project_config.py:

• Edit model, evaluator, and provider:

PROJECT_CONFIG = {
    "project_name": "Aza Man",
    "page_icon": "images/azaman2.png",
    "backstory": (
        "You are Aza Man, an AI-powered personal financial assistant designed to help users manage their budget, ..."
    ),
    "instructions": (
        "..."
    ),
    "youtube_url": "https://youtu.be/8CEyOVjqtRI",
    "author_linkedin": "https://www.linkedin.com/in/chinonsoodiaka/",
    "author_name": "🅱🅻🅰🆀",
    "data_path": "data/azaman.db",
    "model": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "evaluator": "deepseek-ai/DeepSeek-V3",
    "provider": "groq",
    "currency_default": "NGN",
    "state_variables": {
        "username": str,
        "income": float,
        "budget_for_expenses": float,
        "expense": float,
        "expenses": list,
        "savings_goal": float,
        "savings": float,
        "currency": str,
        "summary": str
    },
    "state_defaults": {
        "username": "",
        "income": 0.0,
        "budget_for_expenses": 0.0,
        "expense": 0.0,
        "expenses": [],
        "savings_goal": 0.0,
        "savings": 0.0,
        "currency": "",
        "summary": ""
    },
    "tools": ["set_username", "budget", "log_expenses", "math_tool"],
    "theme": {
        "primary_color": "#FF0000",
        "dark_bg": "#0A0A0A",
        "card_bg": "#1A1A1A"
    }
}

7. Run the Application:

streamlit run app.py

8. Visit http://localhost

.

9. Troubleshooting:

• API Key Errors: Ensure valid keys in .env. Obtain from Groq, OpenRouter, or TogetherAI.
• SQLite Issues: Verify data directory exists (mkdir -p data) and is writable.
• Test Failures: Run pytest --cov=src tests/ to diagnose. Update tests for Pydantic errors if needed.

10. Deployment:

• Local:

streamlit run app.py 

Access: http://localhost

.

• Render:
  Azaman on Render.
• Streamlit Cloud:
  Azaman on Streamlit.

11. Maintenance:

• Database: Monitor data/azaman.db for size and backups.
• Logs: Check data directory for error logs.
• Updates: Pull regularly (git pull origin main) to stay in sync.

10. Future Work

• Feature Expansion: Add currency conversion, investment tracking, or debt management tools.
• Multi-User Support: Scale SQLite for concurrent users with Kubernetes.
• Multimodal Capabilities: Integrate image processing (e.g., receipt scanning) with GPT-4o.
• Guardrails: Add safety tests for HTML sanitization and data leak prevention.
• Resilience: Implement retry with exponential backoff and timeout handling for LLM calls.
• MCP: Adopt Model Context Protocol for standardized tool integration.

11. License

Aza Man is licensed under the MIT License.

12. Acknowledgments

Thanks to ReadyTensor and AAIDC2025 mentors for guidance.

SOURCE FILES - Github repo

LinkedIn - Blaq

---