# Forward-Deployed Agent Lab

[![CI](https://github.com/YihengLi-1/forward-deployed-agent-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/YihengLi-1/forward-deployed-agent-lab/actions/workflows/ci.yml)

A production-shaped, synthetic service-business agent that demonstrates the work between a model demo and a usable customer system: workflow discovery, grounded answers, tool boundaries, human escalation, evaluation, voice integration, and Kubernetes deployment.

This repository contains **no client data or client code**. The fictional `Northstar Clinic` dataset was written for reproducible testing. The operating pattern is informed by hands-on work helping small service businesses adopt AI workflows; see the [anonymized case study](docs/case-study.md).

## System at a glance

```text
Web / Voice / MCP client
          |
          v
  FastAPI + MCP adapters
          |
          v
  deterministic route + safety boundary
      /          |           \
 knowledge    intake tool    human handoff
 citations    pending only   normal / urgent
          |
          v
 tests + synthetic evaluation + Kubernetes runtime controls
```

## What is implemented

- FastAPI endpoints for agent responses, voice-ready SSML/audio, health, readiness, and evaluation
- Deterministic retrieval over an approved bilingual knowledge base with source citations
- Explicit escalation for emergencies, professional judgment, and ungrounded questions
- MCP tools for knowledge search, intake collection, and human escalation
- Local macOS text-to-speech adapter with no external data transfer
- Reproducible synthetic evaluation for route, handoff, tool-selection, and grounding behavior
- Compact BERT intent-router fine-tuning experiment, kept outside the deterministic safety boundary
- Docker image and Kubernetes Deployment, Service, HPA, probes, resource limits, and NetworkPolicy
- Automated API, core-engine, MCP-tool, evaluation, and deployment-manifest tests

## Run locally

Python 3.11–3.13 is supported.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest
python scripts/run_eval.py
uvicorn field_agent_lab.api:app --reload
```

Open `http://127.0.0.1:8000/docs` for the interactive API.

### Grounded knowledge request

```bash
curl -s http://127.0.0.1:8000/v1/agent/respond \
  -H 'content-type: application/json' \
  -d '{"message":"Do you accept HSA cards?","locale":"en-US"}'
```

The response includes a `knowledge` route and citations to the approved payment document.

### Scheduling request

```bash
curl -s http://127.0.0.1:8000/v1/agent/respond \
  -H 'content-type: application/json' \
  -d '{"message":"I want to book an appointment","customer_id":"demo-123"}'
```

The system returns a `collect_intake` tool call and explicitly says that staff must confirm availability.

### Voice-ready response

```bash
curl -s http://127.0.0.1:8000/v1/voice/respond \
  -H 'content-type: application/json' \
  -d '{"message":"When are you open?","generate_audio":false}'
```

Set `generate_audio` to `true` on macOS to return base64-encoded AIFF audio generated by the local `say` provider.

## MCP server

```bash
field-agent-mcp
```

Tools:

- `search_service_knowledge`
- `collect_intake`
- `escalate_to_human`

The MCP interface reuses the same core engine as the HTTP API, so safety and grounding behavior do not drift by channel.

## Compact-model experiment

Install the optional training dependencies and run:

```bash
python -m pip install -e ".[train]"
python training/train_router.py
```

The script fine-tunes `prajjwal1/bert-tiny` on four synthetic intent classes and writes transparent metrics to `artifacts/router_metrics.json`. The model is an experiment; deterministic rules remain the safety boundary.

## Deployment

```bash
docker build -t forward-deployed-agent-lab .
kubectl apply -f deployment/k8s.yaml
```

The manifest intentionally includes readiness/liveness probes, non-root execution, dropped Linux capabilities, resource requests/limits, horizontal autoscaling, and a network policy.

## Evidence and limitations

Generated reports are committed under `artifacts/` after execution. All benchmark cases are visible in `data/eval_cases.jsonl`. The dataset is small and synthetic, so the reported score is a regression baseline—not a claim of clinical quality or production generalization.