Giovanni Zappa

<!DOCTYPE html>

Giovanni Zappa Portfolio

hebrew_vocab_hub — API & Database

FastAPI PostgreSQL SQLAlchemy async Pydantic v2 Docker Compose pg_trgm Python pytest

13,000 Hebrew lemmas. 150,000 unique word forms. Every conjugation, every root, every translation — queryable in milliseconds.

A production-ready REST API and web interface built on top of a custom-scraped Hebrew vocabulary dataset. Search words by meaning (in English), by Hebrew form, by root, by part of speech, or by Latin transcription — with fuzzy matching powered by PostgreSQL trigrams. Each result returns the full conjugation table, bilingual example sentences, and a real-world frequency score from Israeli songs, news, and YouTube.

Spin up the entire stack — Postgres, data import, and API — with a single docker compose up.

What makes it interesting

  • 5 search dimensions — meaning, word form, root, part of speech, transcription — each with a deep mode that reaches inside conjugation cells
  • Fuzzy transcription search — type katav or catav, get שָׁלוֹם back. Exact matches surface first, trigram fallback handles typos and transliteration variants
  • Normalized relational schema — roots, lemmas, inflected forms, conjugation cells, sentences, and frequency data all properly linked; GIN indexes on every searchable column
  • Dual interface — clean JSON REST API (/api/*) and a server-rendered HTML web UI sharing the same query layer
  • One-command deploy — Docker Compose orchestrates Postgres, schema init, data import, and the API with health checks and correct startup order

API at a glance

GET /api/search?query=peace&type=meaning
GET /api/search?query=כתב&type=word&deep=true
GET /api/search?query=katavti&type=transcription
GET /api/lemmas/{uuid}          → full conjugation tables + sentences + frequency
GET /api/browse?page=2          → paginated alphabetical index
// GET /api/lemmas/{uuid}
{
  "hebrew": "כָּתַב",
  "transcription": "katav",
  "meaning": "to write",
  "root": { "display": "כ - ת - ב" },
  "conj_tables": [ ... ],
  "sentences": [
    { "sentence": "הוא כתב מכתב.", "translation": "He wrote a letter." }
  ],
  "sources": { "songs": 12, "news": 34, "youtube": 5, "total": 51 }
}

Getting Started

  • Clone: git clone https://github.com/gzappaa/hebrew_vocab_hub_API
  • Setup: python DATABASE/setup_data.py (downloads dataset, creates env files)
  • Run: docker compose up --build → API live at http://localhost:8000
  • Tests: cd API && pytest / cd DATABASE && pytest

hebrew_vocab_hub — Data Analysis

pandas Jupyter SQL matplotlib / seaborn Gemini API Power BI Excel Python

Does Hebrew vocabulary follow Zipf's law? Do songs, news, and YouTube really speak differently? Is a word's frequency predictable from how many domains it shows up in?

The analysis and reporting layer built on top of hebrew_vocab_hub_API's dataset — three Jupyter notebooks covering exploratory analysis, cross-source vocabulary comparison, and a statistical test of linguistic patterns, followed by an Excel workbook and a Power BI dashboard built from the same queries.

What makes it interesting

  • Confirmed Zipf's law in the dataset's word frequency distribution (power-law exponent ≈ -1), with an explicit caveat that the frequencies reflect the scraped sources, not general spoken Hebrew
  • LLM-assisted semantic labeling — used the Gemini API to classify the top 50 words per source into register categories (emotional/social, public/formal, informal/everyday, neutral), then compared distributions across songs, news, and YouTube
  • A real hypothesis test — checked whether words appearing across more sources have higher frequency (they do), with a full limitations section covering corpus representativeness, source imbalance, and unvalidated LLM labels
  • Root productivity analysis — surfaced which of Hebrew's tri-consonantal roots generate the largest families of derived words in the dataset
  • Same data, three formats — the notebooks, a 9-sheet Excel workbook, and a 3-page Power BI dashboard all trace back to the same Postgres queries, so nothing is hand-copied between them

At a glance

01_eda.ipynb                 → dataset structure, POS distribution, Zipf's law check
02_source_comparison.ipynb   → vocabulary overlap + LLM semantic register labeling
03_linguistic_patterns.ipynb → source coverage vs. word frequency, limitations & bias

excel/hebrew_vocab_hub_report.xlsx  → 9-sheet export, same data source as the dashboard
powerbi/hebrew-vocab-hub-analysis.pbix + .pdf

Getting Started

  • Clone: git clone https://github.com/gzappaa/hebrew-vocab-hub-analysis
  • Install: pip install -r requirements.txt
  • Connect: point .env at the same Postgres instance used by hebrew_vocab_hub_API
  • Run notebooks from notebooks/, or regenerate the Excel workbook: python scripts/generate_workbook.py

hebrew_vocab_hub

Scrapy Playwright MongoDB MySQL PostgreSQL JSONB Python pandas GitHub Actions

A data pipeline that builds a structured Hebrew vocabulary dataset from multiple real-world Israeli sources — dictionary entries, song lyrics, news articles, and YouTube comments — and outputs a single unified JSON ready for use in language learning APIs, apps, or databases.

The core challenge was Building a robust multi-source data pipeline across heterogeneous Hebrew data sources, dealing with rate limits, API restrictions, and inconsistent web structures, while ensuring ethical scraping practices and data normalization in a language outside my full fluency.

GitHub Repository

Full code and instructions are available at: https://github.com/gzappaa/hebrew_vocab_hub

What it produces

~13,000 Hebrew words, each entry containing meanings with niqqudot, transcription, root, part of speech, full conjugation/declension tables, bilingual example sentences, and real-world frequency across songs, news, and YouTube.

{
  "word": "חברה",
  "multiple_meanings": true,
  "meanings": [
    { "hebrew": "חֶבְרָה", "transcription": "chevra", "meaning": "company, society", ... },
    { "hebrew": "חֲבֵרָה", "transcription": "chavera", "meaning": "girlfriend; female friend", ... }
  ],
  "sentences": [
    { "sentence": "החברה הזו גדולה.", "translation": "This company is big.", "source": "reverso" }
  ],
  "sources": { "songs": 12, "news": 45, "youtube": 8, "total": 65 }
}

The dataset is PostgreSQL JSONB-ready — insert the whole document into a jsonb column and index on word.

Pipeline

pealim.com → spider_dict + spider_words → dict-complete.json
Spotify Israel charts → lyrics (Genius API + spider_lyrics) → all_lyrics.txt
hadshon.co.il → news articles → hadshon_articles.json
YouTube Data API → trending comments → word_sources.json
Tatoeba API + Reverso (Playwright) → example sentences

final_dataset.py → vocab_dataset.json

Data sources

  • pealim.com — dictionary entries with niqqudot, transcription, conjugation tables
  • hadshon.co.il — Israeli government Hebrew learning site; news articles used for word frequency
  • Spotify Israel top charts — top ~2,000 songs since 2018, filtered for Hebrew titles
  • Genius — song lyrics scraped for each Hebrew track
  • Tatoeba — bilingual example sentences (public API)
  • Reverso Context — bilingual sentences for words missing from Tatoeba, via Playwright
  • YouTube Data API v3 — daily trending video comments from Israel

Getting Started

  • Clone: git clone https://github.com/gzappaa/hebrew_vocab_hub
  • Install: pip install -r requirements.txt && playwright install chromium
  • Full bootstrap: make bootstrap
  • Daily refresh: make daily
  • Tests: make test

Automated Book Data Pipeline

This project is a modular, reproducible, and testable pipeline for scraping, processing, and analyzing book data from Books to Scrape. It collects book information, cleans and analyzes the data, downloads cover images, and generates PDF and Excel reports.

GitHub Repository

Full code and instructions are available at: https://github.com/gzappaa/Automated-Book-Data-Pipeline

Pipeline Modules

  • Scraper: Collects book data using BeautifulSoup + multithreading.
  • Parser: Extracts structured info from HTML catalog and book pages.
  • Data Cleaning: Normalizes categories, converts prices, extracts availability.
  • Cover Downloader: Saves book images as UPC_title.jpg.
  • Analytics: Computes totals, averages, min/max prices, per-category stats.
  • Reporting: Generates PDF and Excel reports.
  • Testing: Unit tests with mocks and CI-ready configuration.
  • Docker: Containerized pipeline for easy reproducibility.

Workflow

scrape books (basic info) → fetch detailed info → clean data → download covers → generate reports

Getting Started

  • Clone the repo: git clone https://github.com/gzappaa/Automated-Book-Data-Pipeline
  • Install dependencies: pip install -r requirements.txt
  • Run scraper: python -m src.scraper
  • Run with Docker: docker build -t book-pipeline . and docker run --rm -v ${PWD}/data:/app/data book-pipeline

Notes

All prices are numeric only (no € symbol), but amounts are in euros. All data outputs (JSON, PDFs, Excel, images) are saved in the data/ folder.

Screenshots / Reports (Optional)

You can include some screenshots of PDFs, Excel sheets, or cover images here to make it more visual.