Zairo AI — Intelligent Financial Analysis with Zai

Finance data gets smart. Spring Boot talks to Python. Python talks to AI. Insights come back.

Zai is the AI microservice for Zairo, built with Python and FastAPI.

The Zairo Spring Boot backend prepares an organization's financial summary and sends it to Zai through a REST API. Zai handles the AI orchestration, sends the summary to the Groq API, processes the generated response, and returns structured financial insights to the Zairo backend.

The goal is simple: keep financial business logic in Spring Boot and keep AI processing isolated in a dedicated Python service.

Architecture

┌─────────────────────┐
│     Zairo API       │
│    Spring Boot      │
│                     │
│  - Authentication   │
│  - Transactions     │
│  - Organization     │
│  - Financial data   │
└──────────┬──────────┘
           │
           │ HTTP
           │ Financial Summary
           ▼
┌─────────────────────┐
│      Zai AI         │
│      FastAPI        │
│                     │
│  - Request handling │
│  - Prompt building  │
│  - LLM orchestration│
│  - Response parsing │
└──────────┬──────────┘
           │
           │ API request
           ▼
┌─────────────────────┐
│      Groq API       │
│       LLM           │
│                     │
│  - Financial        │
│    interpretation   │
│  - Insight          │
│    generation      │
└──────────┬──────────┘
           │
           │ AI response
           ▼
┌─────────────────────┐
│      Zai AI         │
└──────────┬──────────┘
           │
           │ Structured response
           ▼
┌─────────────────────┐
│     Zairo API       │
└─────────────────────┘

Why this split?

Spring Boot handles authentication, authorization, database operations, transactions, and financial business logic.

FastAPI provides a lightweight Python service dedicated to AI orchestration and external model communication.

Groq provides the LLM inference layer used by Zai to transform financial summaries into human-readable insights.

This separation keeps the core financial system independent from the AI implementation.

What Zai Does

Zai receives structured financial information from Zairo and generates insights such as:

Spending trends — Identify major spending patterns and changes.
Budget observations — Highlight unusual or potentially concerning spending.
Category analysis — Identify major expense categories and areas worth reviewing.
Financial insights — Explain important patterns in the organization's financial data.
Executive summaries — Convert complex financial information into concise takeaways.

Zai focuses on interpreting financial data, while Zairo remains responsible for calculating and storing the underlying financial information.

Tech Stack

Component	Technology
Language	Python 3.10+
Framework	FastAPI
API Server	Uvicorn
LLM Provider	Groq API
HTTP Client	HTTPX
API Documentation	OpenAPI / Swagger
Upstream Backend	Spring Boot 3.x / Java 21
Database	PostgreSQL / Neon

Request Flow

The complete flow looks like this:

1. User requests financial analysis
             ↓
2. Zairo calculates/prepares org summary
             ↓
3. Zairo sends summary to Zai
             ↓
4. Zai builds the AI prompt
             ↓
5. Zai sends prompt to Groq
             ↓
6. Groq generates analysis
             ↓
7. Zai processes the response
             ↓
8. Zai returns structured analysis
             ↓
9. Zairo returns the result to the client

Example Request

Zairo sends an organization's financial summary to Zai:

POST /api/analyze
Content-Type: application/json

{
  "orgId": "org-123",
  "summary": {
    "totalIncome": 250000,
    "totalExpenses": 182500,
    "netPosition": 67500
  }
}

Zai sends the relevant information to Groq and processes the resulting response.

Example response:

{
  "orgId": "org-123",
  "analysis": {
    "spendingTrend": "Salaries represent the largest portion of organizational spending.",
    "alerts": [
      "Software spending has increased compared with the previous period.",
      "Current expenses should be monitored against the available budget."
    ],
    "opportunities": [
      "Review recurring software subscriptions.",
      "Evaluate major recurring expenses for potential savings."
    ],
    "executiveSummary": "The organization maintains a positive net position, but recurring software and operational expenses should be monitored."
  }
}

The exact response structure may evolve as the AI service develops.

Getting Started

1. Clone Zairo

Zai is designed to work alongside the main Zairo Spring Boot backend.

git clone https://github.com/Aakashch-code/zairo-api
cd zairo

Configure your PostgreSQL and JWT settings in:

src/main/resources/application.properties

Add the Zai service URL:

zai.api.base-url=http://localhost:8000
zai.api.timeout=30000

Start Zairo:

mvn spring-boot:run

Zairo runs on:

http://localhost:8085

2. Clone Zai

git clone https://github.com/Aakashch-code/zairo-ai
cd zairo-ai

Create a virtual environment:

python3 -m venv .venv

Activate it on Linux/macOS:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the project root:

GROQ_API_KEY=your_groq_api_key
ZAI_PORT=8000
ZAI_HOST=0.0.0.0

Never commit .env or API keys to GitHub.

Add it to .gitignore:

.env
.venv/
__pycache__/

4. Start Zai

Using Uvicorn:

uvicorn main:app --reload --port 8000

Or, if your main.py starts the server directly:

python main.py

Zai will be available at:

http://localhost:8000

Swagger UI:

http://localhost:8000/docs

ReDoc:

http://localhost:8000/redoc

API Endpoints

Zai

POST   /api/analyze    Analyze an organization summary
GET    /health         Service health check

Health Check

GET /health

Example:

{
  "status": "ok"
}

Financial Analysis

POST /api/analyze

Receives the financial summary prepared by Zairo and returns AI-generated insights.

Integration with Zairo

The two services have separate responsibilities.

Zairo — Spring Boot

Authentication and authorization
User and organization management
Transaction management
PostgreSQL persistence
Financial calculations
Financial summaries
Business rules
Communication with Zai

Zai — FastAPI

Receive financial summaries
Build prompts
Communicate with Groq
Process AI responses
Return AI-generated insights

Groq

LLM inference
Natural-language interpretation
Insight generation

This creates a clean separation between deterministic financial logic and AI-powered interpretation.

Project Structure

Zai

zairo-ai/
├── main.py
├── routers/
│   └── analyze.py
├── services/
│   ├── groq_service.py
│   ├── prompt_builder.py
│   └── response_parser.py
├── models/
│   ├── request.py
│   └── response.py
├── config.py
├── requirements.txt
├── .env
└── README.md

Main components

Component	Responsibility
`main.py`	FastAPI application entry point
`routers/`	API endpoints
`groq_service.py`	Communication with Groq
`prompt_builder.py`	Builds prompts from financial summaries
`response_parser.py`	Processes model responses
`models/`	Request and response schemas
`config.py`	Application configuration

Environment Variables

Zai

GROQ_API_KEY=gsk_...
ZAI_PORT=8000
ZAI_HOST=0.0.0.0
LOG_LEVEL=info

Zairo

zai.api.base-url=http://localhost:8000
zai.api.timeout=30000

For production deployments, replace the local Zai URL with the deployed service URL.

Running Both Services

For local development, run the services separately.

Terminal 1 — Zairo

cd zairo
mvn spring-boot:run

http://localhost:8085

Terminal 2 — Zai

cd zairo-ai
source .venv/bin/activate
uvicorn main:app --reload --port 8000

http://localhost:8000

The communication path is:

Zairo :8085
    ↓
Zai :8000
    ↓
Groq API
    ↓
Zai :8000
    ↓
Zairo :8085

Troubleshooting

Zai is not responding

Check whether FastAPI is running:

curl http://localhost:8000/health

Check the interactive API documentation:

http://localhost:8000/docs

Groq authentication error

If you receive an unauthorized response, verify:

GROQ_API_KEY=your_actual_key

Also make sure the .env file is being loaded correctly.

Zairo cannot reach Zai

Check the configured URL:

zai.api.base-url=http://localhost:8000

Then verify that Zai is accessible:

curl http://localhost:8000/health

If Zai is deployed separately, replace localhost:8000 with the deployed service URL.

Design Principle

Keep financial logic deterministic. Let AI handle interpretation.

Zairo is responsible for calculating, validating, storing, and securing financial data.

Zai does not replace the financial backend. It acts as an AI interpretation layer that takes structured financial information and turns it into understandable insights.

This separation allows the AI service to evolve independently while keeping the core financial system stable.

Future Improvements

Structured LLM output validation
Prompt versioning
Model/provider abstraction
Service-to-service authentication
Request timeout and retry handling
Rate limiting
Response caching
Logging and observability
Docker containerization
Production deployment

Prerequisites

Python 3.10+
pip
Git
Running Zairo Spring Boot API
PostgreSQL / Neon for Zairo
Groq API key

Related Project

Zairo — Financial Workspace API

https://github.com/Aakashch-code/zairo-api

License

Open for learning and portfolio purposes.

Author

Built by Aakash Chauhan

Name		Name	Last commit message	Last commit date
app		app
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt
test.py		test.py
test_main.http		test_main.http

Latest commit

History

Folders and files

Repository files navigation