Beaconn.

When emergency services are overwhelmed, volunteers can save countless lives. We help them find those in need, in real time, with case-specific guidance.

Comment

Beaconn. The Civilian Emergency Response Coordination System

When emergency services are overwhelmed, volunteers can save countless lives. We help them find those in need, in real time, with case-specific guidance.

Project overview

  • Purpose: enable quick matching of help requests ("cases") to nearby volunteers ("helpers") with LLM-based guidance and audit trails.
  • Architecture:
    • backend/ — FastAPI + service layer, agent orchestration, DB helpers
    • frontend/ — React + TypeScript UI (dev server + production build)
    • backend/database/ — Postgres + PostGIS docker-compose and SQL init scripts
    • agents use multi-model LLM support (Bedrock / other providers) and LangSmith for telemetry (optional)
  • Key capabilities: agent orchestration, spatial matching (PostGIS), assignment lifecycle, caller/helper guidance generation, telemetry.

How Beaconn Meets the Three Tracks (Implemented features only)

Agent Iron Man: robustness, efficiency, production readiness

  • Dual-model strategy: Haiku for short guides, Sonnet for structured extraction (services/research.py).
  • Background processing via daemon threads for async agent runs (services/*, agent_graph.py).
  • Postgres + PostGIS for spatial queries and persistence (backend/database).
  • Idempotent DB operations and transactional helpers (get_db_cursor()).
  • Health endpoint and FastAPI (/health, /docs) for service checks.
  • Replaced unsafe eval with ast.literal_eval to eliminate arbitrary code execution (backend/agent_tools.py).

Agent Glass Box — transparency and traceability

  • Audit trail: actions and updates logged to DB (updates table).
  • Persisted artifacts: caller_guides and helper_guides tables with research_query, research_results_summary, guide_text.
  • Structured extraction: InputProcessingAgent produces parsed JSON used to update case fields (services/research.py).
  • LangSmith telemetry integration supported and documented.
  • Open API with autogenerated docs (FastAPI) to inspect endpoints and artifacts.

Dear Grandma — adversarial hardening (implemented mitigations)

  • Removed arbitrary code execution; safe parsing now used (ast.literal_eval).
  • Consolidated and audited tool list to reduce unexpected tool invocations.
  • Input validation and safe defaults applied when parsing LLM outputs (services/*).
  • DB constraints and ON CONFLICT upserts prevent duplicate/ambiguous guide records (migrations / services/guides.py).
  • Audit logs and stored research artifacts enable post‑hoc detection of suspicious behavior.

Important env example files (please configure before running)

  • backend/.env.example — located at backend/.env.example
    • Copy to backend/.env and edit before starting backend:
    • cp backend/.env.example backend/.env
    • Typical variables included or expected:
    • TEAM_ID=
    • API_TOKEN=
    • DATABASE_URL=postgresql://beacon_user:beacon_local_dev@localhost:5432/beacon
    • LANGSMITH_API_KEY=
    • BEDROCK_API_KEY=
    • PROVIDER_... (other provider-specific vars)
  • frontend/.env.example — located at frontend/.env.example
    • Copy to frontend/.env and edit before starting frontend:
    • cp frontend/.env.example frontend/.env
    • Typical variables:
    • VITE_API_BASE_URL=http://localhost:8000/api
    • VITE_MAP_API_KEY= (if using map/routing services)

Requirements

  • Docker & docker-compose (for running Postgres + PostGIS)
  • Python 3.10+ (or as specified by backend/requirements.txt)
  • Node.js 16+ / npm or yarn for frontend
  • Optional: account/keys for Bedrock / LangSmith / other LLM providers

Setup (development)

  1. Clone repo

  2. Database (Postgres + PostGIS)

    • cd backend/database
    • docker-compose up -d
    • Initialize DB schema & seed data:
      • psql -h localhost -U beacon_user -d beacon -f init.sql
    • Apply guides migration (if present):
      • psql -h localhost -U beacon_user -d beacon -f migrations/001_add_guides_tables.sql

  3. Backend environment

    • Copy example env and edit:
      • cp backend/.env.example backend/.env
      • Edit backend/.env to set DATABASE_URL and any provider keys (LANGSMITH_API_KEY, BEDROCK_API_KEY, TEAM_ID, etc.)
    • Install Python dependencies:
      • cd backend
      • python -m venv .venv && source .venv/bin/activate
      • pip install -r requirements.txt
    • Start backend (dev):
      • ### Option A: run via uvicorn (recommended for FastAPI)
      • uvicorn app:app --reload --host 0.0.0.0 --port 8000
      • ### Option B: legacy entrypoints
      • python main.py
      • or python agent_graph.py (for agent-only runs)
    • API will be available at: http://localhost:8000
    • Open docs: http://localhost:8000/docs

  4. Frontend environment

    • Copy example env and edit:
      • cp frontend/.env.example frontend/.env
      • Edit VITE_API_BASE_URL and any map/API keys
    • Install and run:
      • cd frontend
      • npm install
      • npm run dev
    • Default dev server: http://localhost:5173

How to run (end-to-end dev)

  1. Ensure Postgres container is up and DB initialized (see Database step).
  2. Start backend as above.
  3. Start frontend as above.
  4. Use the frontend to create users/cases or exercise APIs directly with curl/Postman.

Basic API smoke tests (curl examples)

Notes about agent processing & guides

  • Case creation triggers background agent processing (fire-and-forget in current prototype). Guides (caller/helper) may take a few seconds to appear. Poll endpoints:
    • GET /api/cases/{case_id}/caller-guide
    • GET /api/assignments/{id}/helper-guide

Running automated (or manual) tests

  • There is no central test suite included in the repo root; check backend/tests or frontend/tests if present.
  • Manual end-to-end testing can be done with the curl examples above after starting backend and frontend.
  • To run any Python tests (if shipped):
    • cd backend
    • pytest -q
  • To run any frontend tests (if shipped):
    • cd frontend
    • npm test

Configuration & secrets

  • Never commit real secrets. Use .env and/or a secrets manager.
  • When running LLMs (Bedrock, Anthropic, etc.) check quotas and costs before experiments.
  • LANGSMITH_API_KEY is optional but recommended for traceability during development.

Troubleshooting / common issues

  • DB connection errors:
    • Confirm DATABASE_URL in backend/.env points to running Postgres container and credentials match docker-compose.
  • Agent errors:
    • Check backend logs; some agent pipelines use external LLMs and will fail if keys are missing.
  • Frontend CORS:
    • Ensure backend allows the frontend origin or run both on localhost with default ports.

Built With

Share this project:

Updates