🏢 BuildWise - AI Building Management System

An AI-powered Building Cost & Rent Management System that combines deterministic financial calculations with intelligent document retrieval and natural language understanding.

🎯 Project Overview

BuildWise is a proof-of-concept system designed to manage:

• Building and flat information
• Tenant management
• Rent calculations
• Utility bills (electricity, gas, water)
• Property taxes and service charges
• AI-powered query answering using RAG (Retrieval Augmented Generation)

🏗️ Architecture

┌─────────────────┐
│  React Frontend │
│   (Port 3000)   │
└────────┬────────┘
         │
         │ HTTP REST API
         │
┌────────▼────────┐
│  FastAPI Backend│
│   (Port 8000)   │
├─────────────────┤
│   AI Agent      │
│   ├─ Intent     │
│   ├─ RAG        │
│   └─ Tools      │
├─────────────────┤
│  Calculations   │
│  (Deterministic)│
└─────────────────┘

Key Design Principles

1. Hybrid Approach: Deterministic Python functions for all monetary calculations, LLMs only for reasoning and intent classification
2. RAG-Based Knowledge: Document retrieval using FAISS for answering policy and rule questions
3. Tool-Calling Architecture: LLM classifies intent and calls appropriate calculation functions
4. Memory Optimized: Designed to run on 16GB RAM using lightweight models
5. Production-Ready: Type hints, validation, error handling, and containerization

🚀 Quick Start with Docker

Prerequisites

• Docker
• Docker Compose
• 16GB RAM minimum
• Linux/WSL2 (Ubuntu 24.04 recommended)

Installation Steps

1. Clone or navigate to the project directory:

cd /home/pyro/poc/BuildWise

2. Build and start the containers:

docker compose up --build

This will:

• Build the backend (FastAPI + AI models)
• Build the frontend (React)
• Start both services
• Backend will be available at http://localhost:8000
• Frontend will be available at http://localhost:3000

3. Access the application:

• Open your browser to http://localhost:3000
• The API documentation is at http://localhost:8000/docs

Stopping the Application

docker compose down

To remove volumes as well:

docker compose down -v

🛠️ Local Development Setup (Without Docker)

Backend Setup

1. Create Python virtual environment:

cd backend
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Run the backend:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

The backend will start at http://localhost:8000

Frontend Setup

1. Install Node.js dependencies:

cd frontend
npm install

2. Start the development server:

npm start

The frontend will start at http://localhost:3000

📊 Tech Stack

Backend

• Python 3.11: Core language
• FastAPI: Web framework
• Pydantic: Data validation
• PyTorch: Neural network framework
• HuggingFace Transformers: Pre-trained models
• Sentence-Transformers: Text embeddings
• FAISS: Vector similarity search

Frontend

• React 18: UI framework
• Axios: HTTP client
• Nginx: Production web server

Infrastructure

• Docker: Containerization
• Docker Compose: Multi-container orchestration

🧠 AI Components

1. RAG Pipeline (backend/core/rag.py)

Retrieval Augmented Generation for answering questions about building policies and rules.

• Embedding Model: sentence-transformers/all-MiniLM-L6-v2 (384 dimensions)
• Vector Store: FAISS with L2 distance
• Documents: Pre-loaded with 10 sample policy documents
• Top-K Retrieval: Returns 3 most relevant documents per query

Sample Documents:

• Rent calculation policies
• Utility bill calculation rules
• Property tax guidelines
• Service charge distribution
• Late payment policies
• Deposit and refund rules

2. AI Agent (backend/core/agent.py)

Intelligent agent that classifies intent and routes to appropriate tools.

Intent Classification:

• calculate_rent: Rent-related calculations
• calculate_utility: Utility bill calculations
• calculate_tax: Property tax calculations
• calculate_service_charge: Service charge calculations
• get_information: Policy/rule questions (uses RAG)
• general_query: General questions

Tool Calling:

• Extracts parameters from natural language queries
• Validates inputs
• Calls deterministic calculation functions
• Returns structured JSON results

3. Calculation Functions (backend/core/calculations.py)

Deterministic financial calculations using Python's Decimal for precision.

Available tools:

• calculate_rent(): Base rent × location multiplier + amenities
• calculate_utility_bill(): Units × rate + fixed charge + tax
• calculate_property_tax(): (Value - exemptions) × tax rate
• calculate_service_charge(): Base charge ÷ flat count + additional services
• calculate_monthly_cost_breakdown(): Total monthly expenses

📡 API Endpoints

Buildings

• POST /buildings/ - Create a new building
• GET /buildings/ - List all buildings
• GET /buildings/{id} - Get building details

Flats

• POST /flats/ - Create a new flat
• GET /flats/ - List all flats
• GET /flats/{id} - Get flat details

Tenants

• POST /tenants/ - Create a new tenant
• GET /tenants/ - List all tenants
• GET /tenants/{id} - Get tenant details

Utility Bills

• POST /utility-bills/ - Create a utility bill
• GET /utility-bills/ - List all utility bills
• GET /utility-bills/{id} - Get bill details

Taxes

• POST /taxes/ - Create a tax record
• GET /taxes/ - List all taxes
• GET /taxes/{id} - Get tax details

AI

• POST /ai/query - Ask the AI assistant a question

Health

• GET /health - Health check endpoint

🎮 Usage Examples

Using the AI Assistant

Calculate Rent:

Query: "Calculate rent for 1200 sqft with base rent 1000"
Response: Detailed calculation with total rent

Utility Bill:

Query: "Calculate electricity bill for 150 units at 0.15 per unit"
Response: Subtotal, tax, and total amount

Policy Questions:

Query: "What is the late payment policy?"
Response: Retrieved from RAG with source documents

Property Tax:

Query: "Calculate property tax for 500000 at 1.5% rate"
Response: Detailed tax calculation

Using the API Directly

Create a Building:

curl -X POST http://localhost:8000/buildings/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunset Towers",
    "address": "123 Main Street",
    "total_floors": 10,
    "total_flats": 40
  }'

AI Query:

curl -X POST http://localhost:8000/ai/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Calculate rent for 1000 sqft with base rent 800"
  }'

📁 Project Structure

BuildWise/
├── backend/
│   ├── core/
│   │   ├── __init__.py
│   │   ├── agent.py          # AI agent with tool calling
│   │   ├── calculations.py    # Deterministic calculations
│   │   └── rag.py            # RAG pipeline
│   ├── models/
│   │   ├── __init__.py
│   │   └── schemas.py        # Pydantic models
│   ├── data/
│   │   ├── documents.json    # RAG documents
│   │   └── faiss_index/      # FAISS vector store
│   ├── main.py               # FastAPI application
│   ├── database.py           # In-memory database
│   ├── requirements.txt      # Python dependencies
│   └── Dockerfile
├── frontend/
│   ├── public/
│   │   └── index.html
│   ├── src/
│   │   ├── App.js            # Main React component
│   │   ├── App.css           # Styles
│   │   ├── index.js          # Entry point
│   │   └── index.css
│   ├── package.json
│   ├── nginx.conf            # Nginx configuration
│   └── Dockerfile
├── docker-compose.yml
├── .gitignore
├── .env.example
├── README.md
└── TECHNICAL.md              # Technical deep-dive

🔧 Configuration

Environment Variables

Copy .env.example to .env and configure:

PYTHONUNBUFFERED=1
API_HOST=0.0.0.0
API_PORT=8000

Memory Optimization

The system is configured for 16GB RAM:

• Uses CPU-only inference (no GPU required)
• Lightweight embedding model (all-MiniLM-L6-v2)
• Simple agent without heavy LLM (can be upgraded to phi-2 or similar)
• FAISS flat index (L2 distance)

Upgrading to Larger Models

To use a full LLM like Phi-2 (uncomment in agent.py):

• Change SimpleLLMAgent to LLMAgent in main.py
• Requires additional 3-4GB RAM
• First run will download ~2.7GB model

🧪 Testing

Test Backend Manually

cd backend
source venv/bin/activate
python -m pytest  # If you add tests

Test API Endpoints

Use the interactive API docs at http://localhost:8000/docs

Test Frontend

cd frontend
npm test

📈 Performance Considerations

• Cold Start: First request takes ~10-30 seconds (model loading)
• RAG Search: ~100-500ms per query
• Calculations: <1ms (deterministic Python)
• Memory Usage: ~2-4GB for base system, 5-8GB with full LLM

🚨 Troubleshooting

Docker Issues

Port Already in Use:

docker compose down
sudo lsof -i :8000  # Check what's using port 8000
sudo lsof -i :3000  # Check what's using port 3000

Container Won't Start:

docker compose logs backend
docker compose logs frontend

Backend Issues

Module Not Found:

cd backend
pip install -r requirements.txt

FAISS Index Missing: The index is built automatically on first run when RAG pipeline initializes.

Frontend Issues

Build Fails:

cd frontend
rm -rf node_modules package-lock.json
npm install

🔒 Security Notes

• No authentication implemented (PoC only)
• No database persistence (in-memory storage)
• CORS enabled for all origins (development only)
• No rate limiting
• No input sanitization beyond Pydantic validation

For Production: Add authentication, persistent database, rate limiting, input sanitization, and HTTPS.

🎓 Learning Resources

See TECHNICAL.md for a comprehensive guide to the AI/ML concepts used in this project, from basic math to production AI systems.

📝 License

This is a proof-of-concept project for educational purposes.

🤝 Contributing

This is a PoC project. For improvements:

1. Add proper database (PostgreSQL/MongoDB)
2. Implement authentication (JWT)
3. Add comprehensive test suite
4. Improve error handling
5. Add logging and monitoring
6. Implement caching (Redis)
7. Add real-time features (WebSockets)

📞 Support

For issues or questions, refer to the technical documentation or API documentation at /docs.

---

Built with ❤️ using FastAPI, React, and AI