{"id":51524186,"url":"https://github.com/embeddedllm/northwind-demo","last_synced_at":"2026-07-08T19:01:26.985Z","repository":{"id":366394603,"uuid":"1222596524","full_name":"EmbeddedLLM/northwind-demo","owner":"EmbeddedLLM","description":"Agentic demo for the northwind dataset. to levels of capabilities increasing with number of tools provided. ","archived":false,"fork":false,"pushed_at":"2026-06-21T15:28:00.000Z","size":177,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T17:15:04.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EmbeddedLLM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T14:17:17.000Z","updated_at":"2026-06-21T15:28:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EmbeddedLLM/northwind-demo","commit_stats":null,"previous_names":["embeddedllm/northwind-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/EmbeddedLLM/northwind-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmbeddedLLM%2Fnorthwind-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmbeddedLLM%2Fnorthwind-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmbeddedLLM%2Fnorthwind-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmbeddedLLM%2Fnorthwind-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EmbeddedLLM","download_url":"https://codeload.github.com/EmbeddedLLM/northwind-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmbeddedLLM%2Fnorthwind-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35275246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-08T19:01:24.755Z","updated_at":"2026-07-08T19:01:26.978Z","avatar_url":"https://github.com/EmbeddedLLM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Northwind Demo — Agentic AI in 4 Levels\n\nA progressive demo showing how an AI agent (Alex) grows in capability across 4 levels,\nusing the **Northwind Traders** dataset — a specialty food import/export company.\n\nThis repo has two apps:\n\n- `backend/` = FastAPI agent server\n- `northwind-demo/` = Svelte frontend\n\n## Quick Start\n\n1. Install dependencies from the repo root:\n\n```bash\nuv sync --all-packages\nuv run playwright install chromium\n```\n\n2. Download the demo database if you do not already have it:\n\n```bash\nwget https://github.com/jpwhite3/northwind-SQLite3/raw/main/dist/northwind.db\n```\n\n3. Create your backend environment file:\n\n```bash\ncp backend/.env.example backend/.env\n```\n\nEdit `backend/.env` and set `BASE_URL`, `API_KEY`, and `MODEL` for your model provider.\n\n4. Start the backend API in one terminal:\n\n```bash\ncd backend\nuv run main.py\n```\n\n5. Start the frontend in a second terminal:\n\n```bash\ncd northwind-demo\nnpm install\nnpm run dev\n```\n\n6. Open the Svelte app at the URL printed by Vite, usually `http://localhost:5173`.\n\nThe frontend is already configured to proxy `/api/*` requests to the backend on `http://localhost:8000`.\n\nIf you only want the API, run steps 1 to 4 and skip the frontend.\n\n## Using The Demo\n\nOpen the Svelte app in your browser and use the level tabs across the top:\n\n- Level 1 asks Alex to turn English questions into SQL\n- Level 2 adds charts and file output\n- Level 3 generates multi-step reports\n- Level 4 uses the workspace filesystem and purchase-order files\n\nPress `Ctrl+Enter` or `Cmd+Enter` in the prompt box to run a question.\nThe Level 4 setup button calls `POST /api/setup`, which wipes `workspace/`\nand regenerates the purchase-order files from `northwind.db`.\n\n---\n\n## Dataset\n\n**Northwind Traders** sells 77 products across 8 categories to 93 customers in 21 countries.\n\n| Table | Description |\n|---|---|\n| Customers | 93 corporate buyers worldwide |\n| Orders + Order Details | 830 orders, ~2,155 line items |\n| Products | 77 products across 8 categories |\n| Suppliers | 29 suppliers from 16 countries |\n| Employees | 9 sales staff |\n| Categories | Beverages, Condiments, Seafood, etc. |\n\nSee the full schema: [`northwind_er.md`](northwind_er.md) or [`northwind_er.dbml`](northwind_er.dbml)\n\n---\n\n## Level 1 — Natural Language to SQL\n\nAlex answers plain-English business questions by generating and running SQL.\nNo SQL knowledge needed from the user.\n\n**Demo prompts:**\n```\nWho are our top 5 customers by total revenue?\nWhich product category generates the most sales?\nWhich employee has closed the most orders?\nHow many orders were shipped to Germany?\nWhat are the top 10 best-selling products?\nWhich suppliers provide the most products?\n```\n\n---\n\n## Level 2 — Visualization \u0026 File Handling\n\nAlex picks between SQL (fetch data) and Python (chart it).\nCharts are rendered by the backend and saved to `backend/reports/chart_*.png`.\n\n**Demo prompts:**\n```\nShow monthly revenue trend as a line chart\nCreate a bar chart of revenue by product category\nPlot a pie chart of orders by country (top 10)\nChart the top 10 best-selling products by revenue\nCompare employee performance with a bar chart\n```\n\nThe backend serves them back through `/api/reports/...`.\n\n---\n\n## Level 3 — Workflow Orchestrator\n\nAlex investigates a business anomaly through multi-step reasoning,\ncreates charts, and compiles everything into a PDF report.\n\n**Demo prompt:**\n```\nGermany is our second-largest market. Investigate whether our revenue there\nis growing or declining, which product categories are driving the change,\nand which employees handle German accounts. Generate a report with charts.\n```\n\n**Other prompts:**\n```\nSeafood sales seem low. Investigate trends and compare against other categories, then generate a report.\nWhich employee is underperforming? Investigate and report.\n```\n\nOutput: `backend/reports/report_\u003ctimestamp\u003e_\u003ctitle\u003e.pdf` + chart PNGs.\nIn this repo, the rendered report files live in `backend/reports/` and are\nserved through `/api/reports/\u003cfilename\u003e`.\n\n---\n\n## Level 4 — Environmental Agent (OS-Level File Operations)\n\nAlex operates the filesystem: creates supplier folders, moves purchase order files,\nzips each folder, and generates a procurement report.\n**Folders appear live in the VS Code sidebar** — the demo \"lightbulb moment\".\n\n### Step 1 — Seed the workspace\n\nUse the Level 4 setup button in the web app before the filesystem demo.\nThat button calls `POST /api/setup`, which runs\n[`backend/workspace.py::setup_workspace()`](backend/workspace.py) and does the\nfollowing:\n\n- deletes the existing `workspace/` directory\n- queries `northwind.db` for products at or below reorder level\n- creates one purchase-order `.txt` file per restock item\n- writes them to `workspace/purchase_orders/`\n\nThe filenames are generated from the supplier and product names, for example:\n```\nworkspace/\n  purchase_orders/\n    Exotic_Liquids__PO002_Chang.txt\n    Exotic_Liquids__PO003_Aniseed_Syrup.txt\n    Formaggi_Fortini_s_r_l__PO031_Gorgonzola_Telino.txt\n    ...\n```\n\n### Step 2 — Run the agent\n\n**Demo prompt:**\n```\nOur procurement team needs to send restock orders today. Find all products\nbelow reorder level, organise their PO files by supplier into folders,\nzip each supplier folder, and generate a procurement summary report.\n```\n\nDuring the Level 4 run, the agent can:\n\n- move purchase-order files into supplier folders with `execute_python`\n- zip each folder with `run_shell`\n- generate a PDF report with the `\u003creport\u003e...\u003c/report\u003e` workflow\n\n### What the audience sees in VS Code:\n\n```\nworkspace/\n  purchase_orders/          ← pre-seeded (18 PO files)\n  Exotic_Liquids/\n    Exotic_Liquids__PO002_Chang.txt\n    Exotic_Liquids__PO003_Aniseed_Syrup.txt\n  Exotic_Liquids.zip\n  Formaggi_Fortini_s_r_l/\n    ...\n  Formaggi_Fortini_s_r_l.zip\n  ...                       ← 15 supplier folders + 15 zips\n  report_\u003ctimestamp\u003e_Procurement_Summary_Report.pdf\n```\n\n---\n\n## Tools per Level\n\n| Tool | L1 | L2 | L3 | L4 |\n|---|:---:|:---:|:---:|:---:|\n| `execute_sql` — query Northwind DB | ✓ | ✓ | ✓ | ✓ |\n| `execute_python` — pandas, matplotlib, shutil | | ✓ | ✓ | ✓ |\n| `generate_report` — produce PDF report | | | ✓ | ✓ |\n| `run_shell` — mkdir, mv, zip inside workspace/ | | | | ✓ |\n\n---\n\n## Re-running the Demo\n\nUse the Level 4 setup button again if you want to reset the workspace before\nrunning the filesystem demo a second time.\n\n---\n\n## Files\n\n```\nnorthwind_demo/\n  backend/                  — FastAPI agent server\n  northwind-demo/                — Svelte frontend\n  northwind.db              — SQLite database\n  workspace/                — All agent outputs saved here\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fembeddedllm%2Fnorthwind-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fembeddedllm%2Fnorthwind-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fembeddedllm%2Fnorthwind-demo/lists"}