{"id":51167089,"url":"https://github.com/navapbc/labs-form-filling-assistant","last_synced_at":"2026-06-26T20:30:26.026Z","repository":{"id":353376970,"uuid":"1207225187","full_name":"navapbc/labs-form-filling-assistant","owner":"navapbc","description":"GenAI-powered tool that completes benefit application forms with caseworker oversight","archived":false,"fork":false,"pushed_at":"2026-04-23T15:51:47.000Z","size":4430,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T17:33:42.616Z","etag":null,"topics":["nava-labs"],"latest_commit_sha":null,"homepage":"https://www.navapbc.com/labs/caseworker-ai-tools/form-filling-assistant","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navapbc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-10T17:58:14.000Z","updated_at":"2026-04-23T15:51:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/navapbc/labs-form-filling-assistant","commit_stats":null,"previous_names":["navapbc/labs-form-filling-assistant"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/navapbc/labs-form-filling-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navapbc%2Flabs-form-filling-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navapbc%2Flabs-form-filling-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navapbc%2Flabs-form-filling-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navapbc%2Flabs-form-filling-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navapbc","download_url":"https://codeload.github.com/navapbc/labs-form-filling-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navapbc%2Flabs-form-filling-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34832916,"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-06-26T02:00:06.560Z","response_time":106,"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":["nava-labs"],"created_at":"2026-06-26T20:30:23.609Z","updated_at":"2026-06-26T20:30:26.016Z","avatar_url":"https://github.com/navapbc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Form-Filling Assistant\n\n**An open-source AI tool that helps caseworkers navigate benefit portals and complete applications on behalf of clients.**\n\nBuilt by [Nava Labs](https://www.navapbc.com/labs/ai-tools-public-benefits), a division of [Nava PBC](https://www.navapbc.com).\n\n**[About](#about)** · **[Features](#features)** · **[Architecture](#architecture)** · **[Getting Started](#getting-started)** · **[Contributing](#contributing)** · **[License](#license)**\n\n---\n\n## About\n\nBenefit navigators and caseworkers spend significant time manually searching multiple databases, navigating benefit portals, and filling out application forms on behalf of the families they serve. This tool uses generative AI to automate that repetitive, time-consuming work — so caseworkers can focus on the people in front of them.\n\nThe [Form-Filling Assistant](https://www.navapbc.com/labs/caseworker-ai-tools/form-filling-assistant) is a  part of Nava Labs' broader [Caseworker Empowerment Toolkit](https://www.navapbc.com/labs/caseworker-ai-tools). \n\n**Initial development and piloting:**\n\nThe Form-Filling Assistant was initially developed with funding from Google.org, in partnership with [Riverside County Children and Families Commission](https://rccfc.org/) and [Amplifi](https://www.amplifi.org/). 20 staff members in public-facing roles are testing the tool in a 4-month pilot period running February to June 2026, and Nava Labs is sharing findings from development and piloting in regular Demo Days:\n- [Developing a Form-Filling Assistant](https://www.navapbc.com/events/nava-labs-demo-day-5)\n- [Piloting a Form-Filling Assistant](https://www.navapbc.com/events/nava-labs-demo-day-7-piloting-a-form-filling-assistant)\n\n\n**Who this is for:**\n\n- **Caseworkers and benefit navigators** who help clients enroll in public benefit programs\n- **Government agencies and social services organizations** developing AI tools for their workforce\n- **Developers** looking to build or adapt AI-assisted casework tools for their context\n\n---\n\n## Features\n\n- **Agentic form-filling** — autonomously navigates benefit portals and populates application forms based on client information\n- **Database lookup** — searches within databases to surface relevant client information\n- **Caseworker oversight** — all actions are reviewable and editable before submission; the caseworker approves every step\n- **Conversational interface** — chat-based UI built on [Next.js](https://nextjs.org) and [shadcn/ui](https://ui.shadcn.com) with accessible components from [Radix UI](https://radix-ui.com) styled with [Tailwind CSS](https://tailwindcss.com)\n- **Flexible AI model support** — works with multiple LLM providers via Vertex AI \n- **Secure authentication** — session-based authentication with Google OAuth, Microsoft Entra ID through [Auth.js](https://authjs.dev)\n- **Persistent chat history** — stores sessions using [Neon Serverless Postgres](https://vercel.com/marketplace/neon) via [Drizzle ORM](https://orm.drizzle.team)\n\n## Architecture\n\n```mermaid\ngraph LR\n    User([User]) --\u003e UI\n\n    subgraph App[\"Next.js Application\"]\n        UI[\"Chat Interface\"] --\u003e Routes[\"API Routes\"]\n        Routes --\u003e Agent[\"AI Agent\"]\n    end\n\n    Agent --\u003e LLMs[\"AI Providers\u003cbr/\u003eAnthropic · OpenAI\u003cbr/\u003eVertex AI · xAI\"]\n    Agent --\u003e Browser[\"Kernel.sh\u003cbr/\u003eRemote Browser\"]\n    Agent --\u003e ExtAPI[\"External API\"]\n    Routes --\u003e DB[\"Neon Postgres\"]\n    Routes --\u003e Redis[\"Upstash Redis\"]\n    Browser -.-\u003e|live stream| UI\n```\n\n## Getting Started\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org) 18+\n- [pnpm](https://pnpm.io) package manager\n- A [Neon](https://neon.tech) database (or any PostgreSQL instance)\n\n### 1. Install dependencies\n\n```bash\npnpm install\n```\n\n### 2. Configure environment variables\n\nCopy the example env file and fill in your values:\n\n```bash\ncp .env.example .env.local\n```\n\nSee the sections below for details on [database](#connecting-to-neon-database) and [API](#connecting-to-an-external-api) configuration.\n\n### 3. Run database migrations\n\n```bash\npnpm drizzle-kit migrate\n```\n\n### 4. Start the development server\n\n```bash\npnpm dev\n```\n\nThe app will be running at [localhost:3000](http://localhost:3000).\n\n---\n\n## Connecting to Neon Database\n\nThis application uses [Neon](https://neon.tech) serverless Postgres as its primary database, managed through [Drizzle ORM](https://orm.drizzle.team).\n\n### Setting up a Neon database\n\n1. Create a free account at [neon.tech](https://neon.tech)\n2. Create a new project and note your connection string\n3. In your `.env.local`, set the `DATABASE_URL`:\n\n```env\nDATABASE_URL=\"postgresql://\u003cuser\u003e:\u003cpassword\u003e@\u003chost\u003e.neon.tech/\u003cdbname\u003e?sslmode=require\"\n```\n\n### Running migrations\n\nDrizzle handles schema migrations. After setting your `DATABASE_URL`:\n\n```bash\n# Generate a new migration after schema changes\npnpm drizzle-kit generate\n\n# Apply pending migrations\npnpm drizzle-kit migrate\n```\n\n### Database schema overview\n\nThe database stores the following entities:\n\n| Table | Purpose |\n|-------|---------|\n| `User` | User accounts (email, name, image) |\n| `Chat` | Chat sessions (title, owner, visibility) |\n| `Message_v2` | Chat messages with multi-part content |\n| `Document` | Artifacts (code, text, images, sheets) |\n| `Vote` | User feedback on messages |\n| `Suggestion` | Suggested edits for documents |\n\n---\n\n## Connecting to an External API\n\nThe application supports integrating with external APIs to extend its capabilities (e.g., form services, document management systems, or other backend services). Below is the general pattern for adding a new API integration.\n\n### 1. Add environment variables\n\nDefine the API credentials in your `.env.local`:\n\n```env\n# External API configuration\nMY_API_BASE_URL=https://api.example.com\nMY_API_CLIENT_ID=your-client-id\nMY_API_CLIENT_SECRET=your-client-secret\n```\n\nAnd add matching entries in `.env.example` for documentation:\n\n```env\nMY_API_BASE_URL=https://api.example.com\nMY_API_CLIENT_ID=****\nMY_API_CLIENT_SECRET=****\n```\n\n### 2. Create an API client module\n\nAdd a new file under `lib/models/` for your API integration:\n\n```typescript\n// lib/models/my-api.ts\n\nconst BASE_URL = process.env.MY_API_BASE_URL;\nconst CLIENT_ID = process.env.MY_API_CLIENT_ID;\nconst CLIENT_SECRET = process.env.MY_API_CLIENT_SECRET;\n\nasync function getAccessToken(): Promise\u003cstring\u003e {\n  const response = await fetch(`${BASE_URL}/oauth/token`, {\n    method: \"POST\",\n    headers: { \"Content-Type\": \"application/json\" },\n    body: JSON.stringify({\n      client_id: CLIENT_ID,\n      client_secret: CLIENT_SECRET,\n      grant_type: \"client_credentials\",\n    }),\n  });\n\n  const data = await response.json();\n  return data.access_token;\n}\n\nexport async function fetchResource(resourceId: string) {\n  const token = await getAccessToken();\n\n  const response = await fetch(`${BASE_URL}/resources/${resourceId}`, {\n    headers: { Authorization: `Bearer ${token}` },\n  });\n\n  if (!response.ok) {\n    throw new Error(`API request failed: ${response.status}`);\n  }\n\n  return response.json();\n}\n```\n\n### 3. Expose as an AI tool (optional)\n\nIf you want the AI assistant to be able to call your API during conversations, register it as a tool in `lib/ai/tools/`:\n\n```typescript\n// lib/ai/tools/my-api-tool.ts\nimport { tool } from \"ai\";\nimport { z } from \"zod\";\nimport { fetchResource } from \"@/lib/models/my-api\";\n\nexport const myApiTool = tool({\n  description: \"Fetch a resource from the external service\",\n  parameters: z.object({\n    resourceId: z.string().describe(\"The ID of the resource to fetch\"),\n  }),\n  execute: async ({ resourceId }) =\u003e {\n    const result = await fetchResource(resourceId);\n    return result;\n  },\n});\n```\n\n### 4. Use in API routes\n\nYou can also call your API directly from Next.js API routes or server actions:\n\n```typescript\n// app/api/my-resource/route.ts\nimport { fetchResource } from \"@/lib/models/my-api\";\n\nexport async function GET(request: Request) {\n  const { searchParams } = new URL(request.url);\n  const id = searchParams.get(\"id\");\n\n  const data = await fetchResource(id);\n  return Response.json(data);\n}\n```\n\n---\n\n## Browser Automation with Kernel\n\n[Kernel.sh](https://onkernel.com) provides remote browser instances that power the application's web automation features. When a user selects the web automation model, the AI agent can control a cloud-hosted Chromium browser to navigate websites, fill out forms, click buttons, and more.\n\n### How it works\n\n1. **Session creation** — When a user starts a web automation chat, the app requests a remote browser from Kernel via the `@onkernel/sdk`\n2. **Browser control** — The AI agent sends commands (navigate, click, fill, type, screenshot, etc.) through the [`agent-browser`](https://www.npmjs.com/package/agent-browser) library, which uses Playwright under the hood\n3. **Live streaming** — Users can watch the browser in real-time via Kernel's embedded live view\n4. **Session replay** — Kernel records browser sessions for debugging and auditing\n5. **Cleanup** — Sessions are automatically destroyed when no longer needed, with a 10-minute idle timeout as a safety net\n\n### Architecture\n\n```mermaid\nsequenceDiagram\n    participant User as User's Browser\u003cbr/\u003e(Live View)\n    participant Agent as AI Agent\u003cbr/\u003e(LLM + Browser Tool)\n    participant AB as agent-browser\u003cbr/\u003e(Playwright)\n    participant K as Kernel.sh\u003cbr/\u003e(Remote Chromium)\n\n    Agent-\u003e\u003eAB: commands (navigate, click, fill)\n    AB-\u003e\u003eK: CDP / WebSocket\n    K--\u003e\u003eAB: page state\n    AB--\u003e\u003eAgent: snapshots\n    K--\u003e\u003eUser: live stream\n```\n\n### Configuration\n\nSet the following in your `.env.local`:\n\n```env\n# Kernel.sh API key — get one at https://onkernel.com\nKERNEL_API_KEY=your-kernel-api-key\n```\n\n### Key files\n\n| File | Purpose |\n|------|---------|\n| `lib/kernel/browser.ts` | Session management — create, cache, and destroy remote browsers |\n| `lib/ai/tools/browser.ts` | AI tool definition — exposes browser commands to the LLM |\n| `app/api/kernel-browser/route.ts` | API route for browser CRUD operations |\n\n\n---\n\n## Key Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `DATABASE_URL` | Yes | PostgreSQL connection string (Neon or local) |\n| `AUTH_SECRET` | Yes | NextAuth.js session secret |\n| `OPENAI_API_KEY` | Yes | Primary AI model provider |\n| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | For OAuth | Google sign-in credentials |\n| `AUTH_MICROSOFT_ENTRA_ID_*` | For OAuth | Microsoft sign-in credentials |\n| `ANTHROPIC_API_KEY` | Optional | Anthropic Claude models |\n| `XAI_API_KEY` | Optional | xAI Grok models |\n| `KERNEL_API_KEY` | For web automation | Kernel.sh remote browser API key |\n| `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` | For shared links | Redis-backed link sharing |\n| `USE_GUEST_LOGIN` | Optional | Set to `true` to enable guest login (bypasses OAuth) |\n| `NEXT_PUBLIC_USE_GUEST_LOGIN` | Optional | Client-side flag — must match `USE_GUEST_LOGIN` |\n| `ENVIRONMENT` | Optional | `dev`, `prod`, or `preview-*` |\n\n### Guest mode\n\nTo use the app without configuring OAuth providers, enable guest mode by setting both `USE_GUEST_LOGIN=true` and `NEXT_PUBLIC_USE_GUEST_LOGIN=true` in your `.env.local`. The login page will automatically sign you in as a guest user with no credentials required.\n\nSee [`.env.example`](.env.example) for the full list of configurable variables.\n\n## Contributing\n\nWe welcome contributions from the community — whether you're fixing a bug, suggesting a feature, or improving documentation.\n\nPlease read our [Contributing Guide](CONTRIBUTING.md) before submitting a pull request. All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).\n\nFor security-related issues, please review our [Security Policy](SECURITY.md) before disclosing publicly.\n\n---\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE). You are free to use, modify, and distribute this software in accordance with the license terms.\n\n---\n\n## About Nava\n\n[Nava PBC](https://www.navapbc.com) partners with government agencies to design and build simple, effective digital services. As a public benefit corporation, we're accountable to our mission: making it easier for people to access the services they need.\n\n[Nava Labs](https://www.navapbc.com/labs) uses philanthropic funding to prototype safety-net innovations that government agencies need but can’t fund directly. We build and test new approaches to delivering public services, evaluate what works, and advocate for scaling proven solutions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavapbc%2Flabs-form-filling-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavapbc%2Flabs-form-filling-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavapbc%2Flabs-form-filling-assistant/lists"}