Project Info

AuthNeuro

This project did not submit a demo video on Devpost.

Inspiration

The inspiration for AuthNeuro was born from a realization of the disconnect between modern medical technology and administrative reality. Having personally experienced the frustration of an insurance denial for a medically necessary surgical procedure, I understand what it feels like to be trapped in administrative limbo. While my own case involved a relatively minor surgery, the denial still resulted in a month-long delay in care. That experience stayed with me. After developing my skills in software development and AI engineering, I wanted to solve this exact problem—the administrative "purgatory" patients face when insurers determine that treatment is not "medically necessary." AuthNeuro is our attempt to bridge that gap and accelerate access to care.

What it does

AuthNeuro transforms neuroimaging data and physician documentation into payer-ready prior authorization packages. The platform: Parses FreeSurfer .stats neuroimaging files Extracts clinically relevant structural metrics Combines imaging findings with physician dictation and clinical notes Generates professional Letters of Medical Necessity (LMNs) Validates generated content against source imaging data Produces submission-ready PDF and email outputs The result is a streamlined workflow that reduces administrative burden while maintaining clinical integrity and traceability.

How we built it

AuthNeuro was architected as a high-integrity, end-to-end clinical workflow. Clinical Reasoning Core We utilized Claude Opus 4.7 to perform the heavy synthesis work, transforming raw structural neuroimaging metrics and physician documentation into professional, persuasive Letters of Medical Necessity. Production Observability To ensure reliability and operational visibility, we instrumented the backend using Sentry for: Real-time error monitoring Performance tracking Latency analysis Production debugging Safety & Compliance The backbone of the project is the Arize AX observability stack, where we implemented a multi-layered LLM-as-a-Judge evaluation framework. Truth Layer A dedicated evaluator mathematically verifies that generated clinical metrics exactly match the source-of-truth neuroimaging files. Narrative Validation Layer A second evaluator reviews outputs for completeness, ensuring the generated letter captures all clinically relevant details and patient context.

Challenges we ran into

Building AuthNeuro was not without significant hurdles. Major Project Pivot Midway through development, we were forced to abandon our original project direction entirely. This required rapid re-scoping, redesigning, and rebuilding under strict time constraints. Overcoming Hallucinations Clinical AI demands a much higher standard than traditional applications. We learned that AI-generated clinical documentation must be treated as a hypothesis rather than a source of truth. To address this, we built programmatic guardrails that continuously cross-reference generated content against authoritative neuroimaging data sources. This approach allowed us to create outputs that are both auditable and clinically trustworthy.

Accomplishments we're proud of

We're incredibly proud of turning a complex vision into a functional, end-to-end prior authorization workflow. True Clinical Integrity The imaging data is honest. Every metric appearing in the final Letter of Medical Necessity is derived directly from parsed FreeSurfer .stats morphometry rather than manual user input. High Clinical Bar We implemented a mandatory KPI attestation step requiring physicians to verify extracted metrics before document generation. This was a deliberate design decision that prioritized patient safety over hackathon shortcuts. Infrastructure Complexity We successfully integrated an extensive healthcare AI stack, including: clabtoolkit Redis LangCache Sentry Claude Opus 4.7 Arize AX Deepgram AgentMail The resulting pipeline remains functional and resilient even when individual services experience configuration issues. Resilient Pivoting Perhaps most importantly, we're proud of our team's ability to completely change directions midway through development and still deliver a polished, production-quality solution.

What we learned

Systems Engineering > Prompt Engineering Enterprise healthcare AI is fundamentally a systems engineering challenge. While model prompting is important, the real innovation lies in building reliable validation, monitoring, and auditing infrastructure around AI systems. The Necessity of Validation Clinical AI becomes safer when generated outputs are treated as hypotheses that must be verified against authoritative data sources. Programmatic guardrails and validation pipelines proved far more valuable than prompt optimization alone. The Power of Pivoting Being forced to abandon our initial idea taught us how to rapidly redefine scope, focus on core value, and still ship a high-quality product under pressure.

What's next

Version 1 proves the full workflow: .stats → metrics → clinical note → LMN → PDF/email submission The next phase is transforming the prototype into a deployable clinical product. What we didn't do (and why) EHR Integration & Auto-Fetch Imaging Hospital integrations require PHI handling, compliance reviews, and institutional access. Manual uploads were sufficient to validate the core concept. Real Payer APIs Insurance authorization APIs remain fragmented and difficult to onboard. For demonstration purposes, AgentMail simulates successful submission workflows. Authentication, Audit Trails & HIPAA Infrastructure This project was intentionally built as a single-user localhost application. Compliance and enterprise security belong in the productization phase, not a weekend hackathon. Appeals & Case Tracking We intentionally scoped the project to first-pass prior authorization generation rather than the full appeals lifecycle. Full Test Suite & CI/CD Given time constraints, we prioritized live API smoke testing over comprehensive automated testing infrastructure. How we move forward Pilot Ingestion Automated watched-folder workflows FHIR-based imaging retrieval by MRN Manual upload retained as a fallback option Trust Layer User authentication Comprehensive audit logging Attending physician sign-off prior to submission Clinical Visualization Provide physicians with interactive 3D visualizations of patient hippocampal, cortical, or vascular structures alongside extracted morphometric metrics. Real Clinical Workflow Expand from document generation to full authorization lifecycle management: Draft Submitted Under Review Approved Denied Appeals Case Tracking

AuthNeuro

Prior authorization for epilepsy surgery — from FreeSurfer morphometry to a payer-ready Letter of Medical Necessity.

AuthNeuro is a clinician-facing workflow that reads a patient's FreeSurfer .stats morphometry report, extracts quantitative neuroimaging measures (hippocampal volume loss, cortical thinning), combines them with a clinical indication, and drafts a Letter of Medical Necessity (LMN) for prior authorization. The finished letter is emailed to a payer review inbox via AgentMail and available as a PDF for the medical record.

What it does

Upload a FreeSurfer morphometry report (e.g. aseg.stats from recon-all)
Review parsed structural measures with payer-threshold context
Document the clinical indication (type or dictate)
Attest to the imaging values that will appear in the letter
Draft the LMN — Claude synthesizes prose grounded in verified metrics
Submit — AgentMail dispatches the PDF to the configured payer outbox automatically

Raw MRI, DICOM, and unscanned NIfTI are not accepted on the main path. AuthNeuro expects post–recon-all text reports such as aseg.stats.

Architecture

flowchart LR
  UI[Streamlit Surgeon Console] --> API[FastAPI backend]
  API --> CLAB[clabtoolkit metrics parse]
  API --> MEM[Agent Memory recall]
  API --> LC[LangCache semantic cache]
  API --> CLAUDE[Claude LMN synthesis]
  API --> REDIS[(Redis job state)]
  API --> PDF[ReportLab PDF]
  API --> MAIL[AgentMail outbox]
  API --> ARIZE[Arize AX tracing]

Layer	Role
Streamlit	Surgeon's Console — upload, intake, attestation, results
FastAPI	Metrics extraction, dictation, authorize pipeline, PDF delivery
clabtoolkit	Parse FreeSurfer `.stats` into structural KPIs
Claude	Draft LMN from clinical text + authoritative metrics
Redis	Exact-response cache and live job status polling
LangCache	Semantic cache for similar prior-auth letters
Agent Memory	Cross-case recall of payer-specific language (optional)
AgentMail	Programmable email outbox with PDF attachment
Deepgram	Clinical dictation transcription (optional)
Arize / Sentry	Observability and error tracking (optional)

Quick start

Prerequisites

Python 3.11+ recommended
Redis running locally (default 127.0.0.1:6379)
API keys for services you want live (minimum: ANTHROPIC_API_KEY for real letter synthesis)

1. Clone and install

git clone <repo-url>
cd authneuro

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -r backend/requirements.txt
pip install -r frontend/requirements.txt

2. Configure environment

cp backend/.env.example backend/.env

Edit backend/.env and set at least:

Variable	Required for	Notes
`ANTHROPIC_API_KEY`	Live LMN drafting	Without it, a placeholder letter is returned
`ANTHROPIC_MODEL`	Claude model	Default: `claude-opus-4-7`
`REDIS_HOST` / `REDIS_PORT`	Job state & cache	Local Redis for development
`DEEPGRAM_API_KEY`	Voice dictation	Optional
`AGENT_MAIL_API_KEY` / `AGENT_MAIL_INBOX_ID`	Auto email dispatch	Optional; PDF still downloadable
`LANGCACHE_*`	Semantic caching	Optional
`AGENT_MEMORY_*`	Payer memory recall	Optional
`ARIZE_*` / `SENTRY_DSN`	Telemetry	Optional

Never commit backend/.env.

3. Start Redis

# macOS (Homebrew)
brew services start redis

# or Docker
docker run -d -p 6379:6379 redis:7

4. Run the backend

From the repository root:

uvicorn backend.main:app --reload --port 8001

Health: http://127.0.0.1:8001/health
OpenAPI docs: http://127.0.0.1:8001/docs

5. Run the frontend

In a second terminal:

cd frontend
streamlit run app.py

Open the URL Streamlit prints (usually http://localhost:8501).

Set API_BASE_URL=http://127.0.0.1:8001 in backend/.env if the API is not on that host/port.

Demo walkthrough

Sample morphometry files live in sample_data/freesurfer_stats/.

File	Suggested MRN	Notes
`MRN-10482_aseg.stats`	`MRN-10482`	Strong atrophy — good threshold demo
`sub-ctl-001_aseg.stats`	`sub-ctl-001`	Milder measures
`sub-epi-005_aseg.stats`	`sub-epi-005`	Epilepsy cohort naming

Suggested flow:

Upload MRN-10482_aseg.stats
Enter MRN MRN-10482, pick a payer, leave target structure as left hippocampus
Enter a clinical indication (e.g. refractory left temporal lobe epilepsy, failed AED trials)
Check the attestation box confirming imaging values
Click Draft Letter of Medical Necessity
Review the letter, AgentMail status, and download the PDF for the chart
Use New case to start another patient (avoids duplicate outbox emails)

API overview

Method	Endpoint	Description
`GET`	`/health`	Service and Redis status
`POST`	`/api/v1/metrics/extract`	Parse `.stats` → structural KPIs
`POST`	`/api/v1/dictate`	Transcribe clinical audio (Deepgram)
`POST`	`/api/v1/authorize`	Full pipeline → LMN + telemetry
`GET`	`/api/v1/jobs/{case_id}/state`	Live job status for UI polling
`GET`	`/api/v1/cases/{case_id}/lmn.pdf`	Download generated PDF
`GET`	`/api/v1/observability`	Sponsor stack status snapshot

Interactive request/response schemas are in Swagger at /docs.

Project structure

authneuro/
├── backend/
│   ├── main.py              # FastAPI app & authorize pipeline
│   ├── requirements.txt
│   └── .env.example         # Environment template (copy to .env)
├── frontend/
│   ├── app.py               # Streamlit entry point
│   ├── pages/
│   │   └── surgeon_console.py
│   ├── assets/              # UI media (e.g. loading animation)
│   └── requirements.txt
└── sample_data/
    └── freesurfer_stats/    # Demo .stats files

Design notes

Metrics are authoritative. Values in the LMN come from the parsed .stats file, not free text in the clinical note. The UI requires explicit physician attestation before drafting.
One draft, one outbox send. Regenerate was removed from the UI because each successful authorize dispatches email via AgentMail. Use New case for a fresh submission.
Cache behavior. Identical cases may be served from Redis without re-calling Claude or re-sending email (skipped_cached_response in telemetry).
Target structures. Supported regions: left/right hippocampus, left/right amygdala (from aseg.stats row names).

Troubleshooting

Symptom	Likely cause	Fix
Button does nothing after draft	Backend 422/502; error may have been transient	Refresh; check red banner; see backend logs
`Could not locate '…' in …stats`	Target structure not in file	Match structure to report (e.g. left hippocampus)
Placeholder letter text	Missing `ANTHROPIC_API_KEY`	Add key to `backend/.env`, restart API
`temperature is deprecated`	Old client params	Use current `backend/main.py` (no temperature on Opus 4.7)
Email not sent	AgentMail keys missing or cache hit	Configure `AGENT_MAIL_` or start New case*
`Redis disconnected`	Redis not running	Start Redis; check `REDIS_HOST` / `REDIS_PORT`

License

Add your license here if open-sourcing.

Analysis

Compare with all teams

View

Metric

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

AnthropicIn code
FastAPIIn code
PythonIn code
RedisIn code
StreamlitIn code

5 of 5 appear in the indexed code.

AI coding agents

CursorCommits

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

192 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.

Project Info

AuthNeuro

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments we're proud of

What we learned

What's next

AuthNeuro

What it does

Architecture

Quick start

Prerequisites

1. Clone and install

2. Configure environment

3. Start Redis

4. Run the backend

5. Run the frontend

Demo walkthrough

API overview

Project structure

Design notes

Troubleshooting

License

Analysis

Technology

AI coding agents

Codebase size

Structure

Interface

Application logic

Languages

Dependencies