Fix OCR gibberish output and add CLAUDE.md

- Fix UTF-8 encoding: Replace mojibake token string with correct
  fullwidth characters for end-of-sentence detection
- Update NGram parameters: ngram_size=20, window_size=50 for more
  aggressive repeat prevention (matching custom_run_dpsk_ocr_pdf.py)
- Fix default prompts: Use proper grounding prompt from config instead
  of bare <image> tag
- Add CLAUDE.md with project documentation for Claude Code

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: MichaelWalker-git

CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DeepSeek OCR Pipeline - A production-ready OCR solution using DeepSeek-OCR with AWS CDK, ECS on GPU instances (g4dn.xlarge), and A2I human review workflows. This is a hybrid architecture combining the Bogdanovich77 DeepSeek-OCR Docker implementation with AWS orchestration.
+
+## Common Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build (compile + lint + synth)
+npm run build
+
+# Run linting
+npm run eslint
+
+# Synthesize CDK templates
+npm run synth
+
+# Deploy to dev environment (requires STAGE=dev env var)
+STAGE=dev npm run deploy:dev
+
+# Deploy with specific profile
+npm run deploy-dev      # uses --profile dev
+npm run deploy-prod     # uses --profile prod
+
+# Build Docker image locally
+npm run build-docker
+
+# View CDK diff
+npm run diff
+
+# Watch mode (hotswap deploys)
+npm run watch
+
+# Destroy dev stacks
+STAGE=dev npm run destroy:dev
+```
+
+## Architecture
+
+### CDK Stage Structure
+
+The app uses a single stage (`DevStage`) defined in `src/lib/stages.ts` that orchestrates six stacks:
+
+1. **KmsStack** - Encryption keys for all resources
+2. **NetworkingStack** - VPC with public/private/isolated subnets across 3 AZs
+3. **EcsStack** - GPU cluster with g4dn.xlarge instances, ALB, auto-scaling (1-10 instances)
+4. **S3Stack** - File storage bucket with KMS encryption
+5. **LambdasStack** - Processing Lambda functions (start processing handler)
+6. **ApiGatewayStack** - REST API with VPC integration to ECS
+
+Stack dependencies: EcsStack depends on KmsStack and NetworkingStack.
+
+### Docker Container (`docker/`)
+
+Custom DeepSeek-OCR implementation based on vLLM OpenAI image. Key customizations:
+- `custom_config.py`, `custom_image_process.py`, `custom_deepseek_ocr.py` - Fixed prompt parameter bugs
+- `start_server.py` - FastAPI server with `/health`, `/ocr/pdf`, `/ocr/image`, `/ocr/batch` endpoints
+- Model downloads from HuggingFace at runtime (`deepseek-ai/DeepSeek-OCR`)
+
+### Key Construct: `DeepSeekOcrEc2GpuConstruct`
+
+Located in `src/constructs/deepseek-ocr-ecs.ts`, this is the core infrastructure construct managing:
+- ECS cluster with GPU-optimized AMI
+- Auto-scaling group with optional spot instance support
+- Application Load Balancer with health checks on port 8000
+- Task definition with 1 GPU, 14GB memory, 3.75 vCPU allocation
+- Model cache persistence via host volume mount at `/mnt/ecs-data/models`
+
+## Environment Variables
+
+Required:
+- `STAGE` - Must be set for deployment (e.g., `dev`)
+- `CDK_DEFAULT_REGION` - AWS region (defaults to `us-east-1`)
+- `CDK_DEFAULT_ACCOUNT` - AWS account ID
+
+Container environment:
+- `MODEL_PATH=deepseek-ai/DeepSeek-OCR` - HuggingFace repository ID
+- `GPU_MEMORY_UTILIZATION=0.85`
+- `MAX_CONCURRENCY=5`
+
+## Deployment Script
+
+`scripts/deploy-ocr-update.sh` provides automated deployment:
+1. Zips and uploads Docker source to S3
+2. Triggers CodeBuild to build and push to ECR
+3. Forces new ECS deployment
+4. Monitors rollout and runs health check
+
+## Projen
+
+This project is managed by Projen. Configuration is in `.projenrc.ts`. After modifying `.projenrc.ts`, run `npx projen` to regenerate project files. Do not manually edit generated files (marked with `// ~~ Generated by projen`).

docker/start_server.py

@@ -159,8 +159,9 @@ def initialize_model():
         )
 
         # Set up sampling parameters
+        # Use more aggressive repeat prevention (matching custom_run_dpsk_ocr_pdf.py)
         from process.ngram_norepeat import NoRepeatNGramLogitsProcessor
-        logits_processors = [NoRepeatNGramLogitsProcessor(ngram_size=30, window_size=90, whitelist_token_ids={128821, 128822})]
+        logits_processors = [NoRepeatNGramLogitsProcessor(ngram_size=20, window_size=50, whitelist_token_ids={128821, 128822})]
 
         sampling_params = SamplingParams(
             temperature=0.1,
@@ -244,9 +245,10 @@ def process_single_image(
     print(f"[DEBUG] Model output (first 100 chars): {repr(result[:100])}")
     print(f"[DEBUG] Model output length: {len(result)} characters")
 
-    # Clean up result
-    if '<｜endâ–ofâ–sentence｜>' in result:
-        result = result.replace('<｜endâ–ofâ–sentence｜>', '')
+    # Clean up result - remove end-of-sentence tokens
+    # Note: The token uses fullwidth characters: ｜ (U+FF5C) and ▁ (U+2581)
+    if '<｜end▁of▁sentence｜>' in result:
+        result = result.replace('<｜end▁of▁sentence｜>', '')
         print(f"[DEBUG] Removed end-of-sentence tokens")
 
     return result
@@ -275,7 +277,7 @@ async def health_check():
 @app.post("/ocr/image", response_model=OCRResponse)
 async def process_image_endpoint(
     file: UploadFile = File(...),
-    prompt: Optional[str] = Form('<image>'),
+    prompt: Optional[str] = Form(None),
     temperature: Optional[float] = Form(None),
     top_p: Optional[float] = Form(None),
     max_tokens: Optional[int] = Form(None),
@@ -297,8 +299,8 @@ async def process_image_endpoint(
         print(f"[DEBUG] Default PROMPT from config: {repr(PROMPT)}")
         print(f"[API] Sampling overrides: temperature={temperature}, top_p={top_p}, max_tokens={max_tokens}")
 
-        # Use provided prompt or default
-        use_prompt = prompt if prompt and prompt.strip() else '<image>'
+        # Use provided prompt or default from config (includes grounding instruction)
+        use_prompt = prompt if prompt and prompt.strip() else PROMPT
         print(f"[DEBUG] Image endpoint selected prompt: {repr(use_prompt)}")
         print(f"[DEBUG] Using custom prompt: {prompt is not None}")
 
@@ -329,7 +331,7 @@ async def process_image_endpoint(
 @app.post("/ocr/pdf", response_model=BatchOCRResponse)
 async def process_pdf_endpoint(
     file: UploadFile = File(...),
-    prompt: Optional[str] = Form('<image>'),
+    prompt: Optional[str] = Form(None),
     temperature: Optional[float] = Form(None),
     top_p: Optional[float] = Form(None),
     max_tokens: Optional[int] = Form(None),
@@ -341,7 +343,7 @@ async def process_pdf_endpoint(
         print(f"[DEBUG] Default PROMPT from config: {repr(PROMPT)}")
         print(f"[API] Sampling overrides: temperature={temperature}, top_p={top_p}, max_tokens={max_tokens}")
 
-       # Read PDF data
+        # Read PDF data
         pdf_data = await file.read()
         print(f"[DEBUG] Read {len(pdf_data)} bytes of PDF data")
 
@@ -358,15 +360,12 @@ async def process_pdf_endpoint(
                 filename=file.filename
             )
 
-        # Use provided prompt or default
-        use_prompt = prompt if prompt else PROMPT
+        # Use provided prompt or default from config (includes grounding instruction)
+        use_prompt = prompt if prompt and prompt.strip() else PROMPT
         print(f"[DEBUG] PDF endpoint selected prompt: {repr(use_prompt)}")
         print(f"[DEBUG] Using custom prompt: {prompt is not None}")
 
         # Process each page
-        results = []
-        use_prompt = prompt if prompt and prompt.strip() else '<image>'
-
         results = []
         for page_num, image in enumerate(tqdm(images, desc="Processing pages")):
             try: