niraj12chaudhary/field-service-ai-assistant

Purpose and entry points

Field-Service Assistant is a local chat system for technicians. It answers only from a Markdown knowledge base and performs controlled work-order actions through Gemini function calling. The backend entry point is backend/main.py; the browser entry is frontend/src/main.jsx, rendering the chat UI in frontend/src/App.jsx.

API and session boundary

FastAPI exposes health and chat APIs from backend/main.py. Chat requests are associated with in-memory conversation sessions, allowing follow-up references such as “mark it complete” to retain prior context. The React client sends requests through the Vite development proxy in frontend/vite.config.js, avoiding browser-to-backend CORS handling during local development.

Agent orchestration

backend/agent.py owns the Gemini interaction loop: it supplies the system instructions, conversation history, and declared tools; receives model function calls; executes server-side tool implementations; then returns tool results to Gemini for a final natural-language response. Gemini is an external runtime dependency, authenticated by GEMINI_API_KEY in backend/.env.

Key boundaries:

• The model proposes actions; it does not directly mutate data.

• Tool results, not model claims, determine whether an operation succeeds.

• Knowledge responses are routed through grounded search rather than open-ended inference.

Enforced work-order tool layer

backend/tools.py is the authorization and business-rule boundary. It implements lookup, technician-scoped listing, status updates, note creation, escalation, and knowledge search. It enforces ownership for the fixed logged-in technician and validates the allowed status progression (Open → In Progress → On Hold → Completed) in code.

Tool arguments and work-order shapes are validated through Pydantic models in backend/models.py. This separation prevents prompt injection or malformed function arguments from bypassing policy enforcement.

Persistence and domain data

backend/data_store.py provides raw JSON read/write access and deliberately contains no business rules. Work orders are persisted in backend/data/work_orders.json; records include assignment, status, plus application-added note and escalation fields. The current implementation is file-backed and suitable for local/single-process use rather than concurrent or durable multi-instance deployment.

Knowledge grounding path

backend/knowledge.py searches the reference content in backend/data/knowledge.md. The search_knowledge tool returns an explicit not-found result when the source does not cover a question, allowing the agent to produce a fixed non-speculative response instead of inventing policy or procedure.

Frontend runtime

The frontend is a minimal React/Vite single-page chat client. frontend/src/App.jsx manages the message list, user input, API submission, and display of assistant responses. It has no separate authentication layer: technician identity is currently established server-side as part of the backend’s controlled execution context.