Israel Air Quality Assistant

A small LangGraph-based project that demonstrates manual tool calling, structured outputs, and a simple workflow-driven assistant.

The assistant accepts a city in Israel, retrieves air-quality data, interprets it, and returns structured health guidance instead of loose text.

---

Project Goal

The goal of this project is to build a small assistant for Israeli cities that demonstrates how a workflow can explicitly call a tool, process the returned data, and produce a reliable structured result.

One-sentence version: We are building a small assistant that turns air-quality data for Israeli cities into reliable, structured health advice.

---

Main Learning Goals

• Manual tool calling — the workflow explicitly calls the air-quality tool in code.
• Structured outputs — the result follows a fixed schema instead of free text.
• Basic LangGraph workflow design — the app is built as a simple graph with clear steps.

---

How It Works

User Input (city)
        ↓
LangGraph StateGraph
        ↓
fetch_air_quality node
        ↓
get_air_quality tool
        ↓
build_report node
        ↓
interpret_air_quality service
        ↓
Structured output shown to user

---

Project Structure

israel-air-quality-assistant/
├── app/
│   ├── graph/
│   │   └── workflow.py
│   ├── tools/
│   │   └── air_quality.py
│   ├── schemas/
│   │   └── air_quality.py
│   ├── services/
│   │   └── interpreter.py
│   └── main.py
└── tests/

---

Core Components

Component	Purpose
get_air_quality(city)	Retrieves air-quality data for a requested Israeli city.
interpret_air_quality(city, aqi)	Converts raw AQI into category, jogging safety, and health advice.
AirQualityReport	Defines the structured output contract of the assistant.
LangGraph workflow	Coordinates the nodes and state transitions from input to final output.

---

Manual Tool Calling Explained

In this project, tool calling is manual because the developer explicitly decides when the tool is invoked and how the returned data is processed.

raw_result = get_air_quality(city)

That call is written directly in the workflow logic. The model is not autonomously deciding whether or when to call the tool. This is the central concept of the project.

---

Structured Output Schema

The assistant returns a fixed result shape with fields such as:

• city
• aqi
• category
• jogging_safe
• advice

This makes the output reliable, predictable, and easy to validate.

---

How to Run

.venv/bin/python -m app.main

The application will prompt for a city name and then return a structured air-quality report.

---

Example Output

Air Quality Report
------------------
City: Tel Aviv
AQI: 42
Category: Good
Jogging safe: True
Advice: Air quality is good. Outdoor activity is safe for most people.

---

Notes on Data Source

The live version may use modeled air-quality data rather than direct official station measurements. This is useful for demonstrating real external tool integration, but it is not the same as local government sensor-grade monitoring.

---

Future Improvements

• Replace modeled AQI with official Israeli monitoring station data.
• Add tests for interpretation logic and workflow behavior.
• Add a web interface or API layer.
• Expand the graph with validation and fallback nodes.

---

Built as a learning project for Manual Tool Calling Basics with LangGraph.