Skip to content

replit.md

Latest commit

 

History

History
154 lines (133 loc) · 9.69 KB

replit.md

File metadata and controls

154 lines (133 loc) · 9.69 KB
Raw

bobSWMM Auto Research

Overview

bobSWMM is an auto-research tool inspired by Karpathy's deep research, specialized for EPA SWMM5 (Storm Water Management Model). It uses AI to conduct deep research on SWMM5 topics and generate comprehensive technical reports with RAG-grounded knowledge.

Stack

  • Monorepo tool: pnpm workspaces
  • Node.js version: 24
  • Package manager: pnpm
  • TypeScript version: 5.9
  • API framework: Express 5
  • Database: PostgreSQL + Drizzle ORM
  • Validation: Zod (zod/v4), drizzle-zod
  • API codegen: Orval (from OpenAPI spec)
  • Build: esbuild (CJS bundle)
  • AI: OpenAI via Replit AI Integrations (gpt-5.2)
  • Frontend: React + Vite + Tailwind CSS + shadcn/ui + Recharts

Features

  • Deep Research: Enter any SWMM5 topic and get a comprehensive AI-generated research report with citations
  • Research Presets: 54+ pre-built research templates across 13 categories with emoji icons
  • Research Depth: Quick (800-1200 words), Standard (2000-3000 words), or Deep (4000-6000 words)
  • RAG Knowledge Base: 8 embedded topics (Green-Ampt, Horton, Curve Number, Dynamic Wave, RTK/RDII, Surcharging, Manning, LID-Bioretention) with manual citations, parameter tables, equations, and source code references. Automatically injected into AI prompts for grounded research.
  • Learning Log: Activity tracker showing which RAG topics were matched per research query, with frequency charts and session history
  • Compare Models: Static 11-feature comparison table: EPA SWMM5 vs ICM SWMM vs SWMM5+ vs HEC-RAS
  • Chat Expert: Interactive chat with a SWMM5-specialized AI assistant
  • Research History: Browse and review past research sessions
  • Export Options: Copy as Markdown, download .md file, or Print/Save as PDF
  • Math Rendering: KaTeX support for LaTeX equations in research reports
  • Hydraulic Calculators: 6 interactive calculators (Green-Ampt, Horton, Curve Number, RTK/RDII, Manning's Pipe, Surcharge) with Recharts live charts linked to SWMM5 source code
  • .inp File Analyzer: Client-side drag-and-drop INP file parsing with diagnostics (no server upload)
  • Source Code Cross-Reference: 40 SWMM5 C functions across 7 categories (Hydrology, Hydraulics, RDII, LID, Quality, Controls, I/O) with search filter and GitHub links
  • Community Hub: 16 curated resources (blogs, forums, source code, manuals, videos, training)
  • Error Code Encyclopedia: 33 SWMM5 error codes with practical diagnosis (cause, check-first list, fix, source code link)
  • Parameter Estimation Wizard: 3-step guided workflow (soil → land use → slope) recommending Green-Ampt/Horton/CN parameters, roughness, depression storage
  • Unit Conversion Hub: 9 conversion groups (flow, infiltration, length, area, Manning's, velocity, volume, rainfall, pressure) with live calculation
  • Design Storm Library: SCS Type I/IA/II/III distributions with hyetograph chart and SWMM5 [TIMESERIES] export (copy/download .dat)
  • .inp Diff Tool: Section-aware comparison of two .inp files with add/remove/modify highlighting and section filters
  • Model Review Checklist: Automated QA/QC for .inp files — parses routing steps, short pipes, missing sections, orphaned nodes, and scores model quality
  • RPT File Dashboard: Parse SWMM5 .rpt report files for health assessment — continuity errors, flooded/surcharged nodes, overall health score
  • ICM Translation Helper: 17 parameter mappings for SWMM5 → ICM model conversion (March 2026 ArcMap deadline reference)
  • PySWMM Code Generator: 6 ready-to-run Python templates (basic run, parameter sweep, calibration, RTC, batch, .inp modify)
  • Historical Timeline: 16 events from 1969 → 2026 covering SWMM I through AI era with color-coded eras
  • Section Explainer: 24 .inp sections with column formats, descriptions, and practical tips

Structure

artifacts-monorepo/
├── artifacts/
│   ├── api-server/         # Express API server with research & chat routes
│   │   └── src/lib/
│   │       ├── swmm5-presets.ts     # 54+ SWMM5 research presets
│   │       └── rag-knowledge.ts     # RAG knowledge base (8 topics)
│   └── bob-swmm/           # React + Vite frontend
│       └── src/
│           ├── pages/
│           │   ├── home.tsx          # Landing page with search
│           │   ├── presets.tsx        # 54+ preset research cards with icons
│           │   ├── research-new.tsx   # Active research SSE streaming
│           │   ├── research-detail.tsx # View past research
│           │   ├── history.tsx        # Research history list
│           │   ├── chat.tsx           # Expert chat
│           │   ├── calculators.tsx    # 6 hydraulic calculators with Recharts
│           │   ├── compare.tsx        # Platform comparison table
│           │   ├── inp-analyzer.tsx   # .inp file parser
│           │   ├── source-code.tsx    # 40-entry source code cross-reference
│           │   ├── community.tsx      # Community Knowledge Hub (16 resources)
│           │   ├── knowledge-base.tsx # RAG Knowledge Base viewer
│           │   ├── learning-log.tsx   # Learning Log (RAG usage tracker)
│           │   ├── error-codes.tsx    # 33 SWMM5 error codes with diagnosis
│           │   ├── parameter-wizard.tsx # 3-step parameter estimation wizard
│           │   ├── unit-converter.tsx  # 9-group SWMM unit converter
│           │   ├── design-storms.tsx   # SCS design storm library with export
│           │   ├── inp-diff.tsx        # .inp file diff tool
│           │   ├── model-review.tsx   # .inp QA/QC model review checklist
│           │   ├── rpt-dashboard.tsx  # .rpt file health dashboard
│           │   ├── icm-translator.tsx # SWMM5 → ICM parameter mapping
│           │   ├── pyswmm-code.tsx    # PySWMM code generator (6 templates)
│           │   ├── timeline.tsx       # Historical timeline (1969→2026)
│           │   └── section-explainer.tsx # .inp section explainer (24 sections)
│           └── lib/
│               ├── source-code-map.ts  # 40 SWMM5 C functions + community links
│               └── inp-parser.ts       # Client-side INP file parser
├── lib/
│   ├── api-spec/           # OpenAPI spec + Orval codegen config
│   ├── api-client-react/   # Generated React Query hooks + TypeScript interfaces
│   ├── api-zod/            # Generated Zod schemas from OpenAPI
│   ├── db/                 # Drizzle ORM schema + DB connection
│   └── integrations-openai-ai-server/  # OpenAI integration
├── scripts/
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── tsconfig.json
└── package.json

Key Backend Files

  • artifacts/api-server/src/routes/research.ts — Research endpoints (presets, start research SSE with RAG injection, sessions CRUD)
  • artifacts/api-server/src/routes/openai.ts — Chat conversation endpoints with SSE streaming
  • artifacts/api-server/src/lib/swmm5-presets.ts — 54+ SWMM5 research presets with emoji icons + system prompts
  • artifacts/api-server/src/lib/rag-knowledge.ts — RAG knowledge base with 8 topics, parameter tables, equations, source code refs

Database Tables

  • conversations — Chat conversations
  • messages — Chat messages (user & assistant)
  • research_sessions — Research sessions with query, depth, status, report, sources, rag_topics (text[])

API Endpoints

Research

  • GET /api/research/presets — List SWMM5 preset topics (includes icon field)
  • POST /api/research/start — Start deep research (SSE stream with RAG context injection)
  • GET /api/research/sessions — List past sessions (includes ragTopics)
  • GET /api/research/sessions/:id — Get session detail (includes ragTopics)
  • DELETE /api/research/sessions/:id — Delete session

Chat

  • GET /api/openai/conversations — List conversations
  • POST /api/openai/conversations — Create conversation
  • GET /api/openai/conversations/:id — Get conversation with messages
  • DELETE /api/openai/conversations/:id — Delete conversation
  • POST /api/openai/conversations/:id/messages — Send message (SSE stream)

SSE Events (Research)

  • { type: "status" } — Progress updates
  • { type: "session_id" } — Session ID for the research
  • { type: "rag_matches", data: [...] } — RAG topics matched to query
  • { type: "content" } — Streaming research report content
  • { type: "sources" } — Extracted sources list
  • { done: true, sessionId } — Research complete

Important Notes

  • Generated types in lib/api-zod/src/generated/ and lib/api-client-react/src/generated/ are manually maintained (orval not fully configured for auto-run)
  • AI Integration uses AI_INTEGRATIONS_OPENAI_BASE_URL and AI_INTEGRATIONS_OPENAI_API_KEY env vars
  • Model: gpt-5.2, use max_completion_tokens not max_tokens
  • DB table names: conversations and messages (not camelCase variants)
  • KaTeX CSS imported in markdown.tsx with dark mode overrides in index.css
  • Recharts installed in bob-swmm frontend for calculators (includes CartesianGrid, ReferenceLine)
  • ragTopics column: text[] in research_sessions table (migration applied manually)
  • CSS: hydro-gradient is plain CSS, cannot use in @apply

Root Scripts

  • pnpm run build — runs typecheck first, then recursively runs build in all packages
  • pnpm run typecheck — runs tsc --build --emitDeclarationOnly using project references
  • pnpm --filter @workspace/api-spec run codegen — regenerate API client hooks and Zod schemas