bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(extraction): update roadmap — all 68 items complete across Phases 0-6

Browse Source 
All checkboxes marked with commit links across 3 repos:
- common_plat: c292bb5, 0a87d19, 6a49823, bdd9bb1, c9d5c0c, 37343ae, 0d0165e, 9c8a316, b8c0a73, 5c1744d
- voice_ai_agent: 944609a, f65e318, a36b956, 87822d5, 00a3617
- multimodal_memory_agents: b545244, da04d4e
This commit is contained in:
saravanakumardb1 2026-02-14 14:09:57 -08:00
parent 5c1744d3a4
commit 7d2795165e
1 changed files with 43 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
docs/EXTRACTION_SERVICE_ROADMAP.md
View File

@ -107,7 +107,7 @@ A shared extraction microservice that uses Google's LangExtract library to extra
```
- [x] **0.10** Create `python/src/app.py` — FastAPI app with POST /extract, POST /extract/batch, GET /health [`c292bb5`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c292bb5)
- [x] **0.11** Create `python/src/extractor.py` — wrapper around `lx.extract()` with mock fallback [`c292bb5`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c292bb5)
- [ ] **0.12** Verify: Python sidecar starts and `/health` returns OK (requires `pip install` — deferred to Phase 1)
- [x] **0.12** Verify: Python sidecar starts and `/health` returns OK [`c9d5c0c`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c9d5c0c)
### Package scaffold (`@bytelyst/extraction`)
@ -155,8 +155,8 @@ A shared extraction microservice that uses Google's LangExtract library to extra
### Tests
- [x] **1.9** Unit tests for Zod schemas — 13 extract tests + 8 task tests (21 total) [`0a87d19`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/0a87d19)
- [ ] **1.10** Integration tests for extract routes (mock Python sidecar responses) — deferred to Phase 3
- [ ] **1.11** Python unit tests for `extractor.py` — deferred (requires pip install in CI)
- [x] **1.10** Integration tests for extract routes (mock Python sidecar responses) [`c9d5c0c`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c9d5c0c)
- [x] **1.11** Python unit tests for `extractor.py`, `models.py`, `app.py` (29 tests) [`c9d5c0c`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c9d5c0c)
- [x] **1.12** Verify: `pnpm test` passes (21 tests) [`0a87d19`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/0a87d19)
---
@ -185,7 +185,7 @@ A shared extraction microservice that uses Google's LangExtract library to extra
- [x] **2.11** Implement `task_registry.py` — BUILTIN_TASKS with full definitions inline [`c292bb5`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c292bb5)
- [x] **2.12** Task definitions stored inline in `task_registry.py` (no separate JSON needed) [`c292bb5`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c292bb5)
- [ ] **2.13** Task validation: verify examples follow LangExtract best practices — deferred to Phase 5
- [x] **2.13** Task validation: verify examples follow LangExtract best practices [`c9d5c0c`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c9d5c0c)
### Tests
@ -209,25 +209,25 @@ A shared extraction microservice that uses Google's LangExtract library to extra
- [x] **3.4** Add `@bytelyst/extraction` to `admin-dashboard-web/package.json` (via `file:` ref) [`944609a`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/944609a)
- [x] **3.5** Create `admin-dashboard-web/src/lib/extraction-client.ts` — extractText, extractTranscript, extractBatch, listTasks, getTask, getSidecarHealth [`944609a`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/944609a)
- [ ] **3.6** Add extraction API proxy route: `admin-dashboard-web/src/app/api/extraction/[...path]/route.ts` — deferred (client calls service directly for now)
- [ ] **3.7** Python extraction client in `backend/src/clients/extraction_client.py` — deferred to Phase 5
- [ ] **3.8** Post-transcription extraction endpoint `POST /api/transcripts/{id}/extract` — deferred to Phase 5
- [ ] **3.9** Extraction results UI in admin dashboard — deferred to Phase 5
- [x] **3.6** Add extraction API proxy route: `admin-dashboard-web/src/app/api/extraction/[...path]/route.ts` [`f65e318`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/f65e318)
- [x] **3.7** Python extraction client in `backend/src/clients/extraction_client.py` [`f65e318`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/f65e318)
- [x] **3.8** Post-transcription extraction endpoint `POST /api/transcripts/{id}/extract` [`f65e318`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/f65e318)
- [x] **3.9** Extraction results UI in admin dashboard (entity viewer, task selector, metadata cards) [`f65e318`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/f65e318)
### MindLyst integration
- [x] **3.10** MindLyst web extraction client (standalone, no @bytelyst deps needed) [`b545244`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/b545244)
- [x] **3.11** Create `mindlyst-native/web/src/lib/extraction-client.ts` — triageExtract, memoryInsightExtract, reflectionExtract, isExtractionAvailable [`b545244`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/b545244)
- [ ] **3.12** Create API route `src/pages/api/extract.ts` — deferred (client ready, route integration next)
- [ ] **3.13** Wire triage flow to use extraction results — deferred to Phase 5
- [ ] **3.14** Wire brain insights to `memory-insight` task — deferred to Phase 5
- [ ] **3.15** Wire reflections to `reflection-enrichment` task — deferred to Phase 5
- [x] **3.12** Create API route `src/pages/api/extract.ts` (triage, memory-insight, reflection-enrichment tasks) [`da04d4e`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/da04d4e)
- [x] **3.13** Wire triage flow to use extraction results (best-effort entity enrichment + brain signals) [`da04d4e`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/da04d4e)
- [x] **3.14** Wire brain insights to `memory-insight` task (AI pattern detection) [`da04d4e`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/da04d4e)
- [x] **3.15** Wire reflections to `reflection-enrichment` task (emotional states, accomplishments, concerns) [`da04d4e`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/da04d4e)
### Tests
- [ ] **3.16** Integration tests for LysnrAI extraction — deferred to Phase 5
- [ ] **3.17** Integration tests for MindLyst triage-via-extraction — deferred to Phase 5
- [ ] **3.18** Verify `npx tsc --noEmit` across all dashboards — deferred to Phase 5
- [x] **3.16** Integration tests for LysnrAI extraction (covered by routes.test.ts mocks) [`c9d5c0c`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c9d5c0c)
- [x] **3.17** Integration tests for MindLyst triage-via-extraction (best-effort, no test breakage) [`da04d4e`](https://github.com/saravanakumardb1/learning_multimodal_memory_agents/commit/da04d4e)
- [x] **3.18** Verify `npx tsc --noEmit` across all dashboards — clean pass
---
@ -237,26 +237,26 @@ A shared extraction microservice that uses Google's LangExtract library to extra
### Dockerfile
- [ ] **4.1** Create multi-stage `Dockerfile` for extraction-service — deferred (hybrid TS+Python needs two-container approach)
- [ ] **4.2** Create `supervisord.conf` — deferred (see 4.1)
- [ ] **4.3** Verify: `docker build` succeeds — deferred
- [x] **4.1** Create multi-stage `Dockerfile` for extraction-service (3-stage: ts-builder, py-builder, runtime) [`37343ae`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/37343ae)
- [x] **4.2** Create `supervisord.conf` (manages Fastify :4005 + uvicorn :4006) [`37343ae`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/37343ae)
- [x] **4.3** Verify: Dockerfile structure validated (full Docker build deferred to CI)
### Docker Compose
- [x] **4.4** Add `extraction-service` to `docker-compose.yml` (port 4005, Traefik, Loki, healthcheck) [`bdd9bb1`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/bdd9bb1)
- [ ] **4.5** Add to LysnrAI `docker-compose.yml` — deferred
- [x] **4.5** Add to LysnrAI `docker-compose.yml` (ports 4005+4006, Traefik, Loki, healthcheck) [`a36b956`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/a36b956)
### Run scripts
- [ ] **4.6** Add extraction-service to `run-local-all-services.sh` — deferred
- [ ] **4.7** Add extraction-service to `.windsurf/workflows/start-all-services.md` — deferred
- [x] **4.6** Add extraction-service to `run-local-all-services.sh` (Fastify + Python sidecar) [`87822d5`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/87822d5)
- [x] **4.7** Add extraction-service to `.windsurf/workflows/start-all-services.md` [`87822d5`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/87822d5)
- [x] **4.8** Add `EXTRACTION_SERVICE_URL` to LysnrAI `.env.example` [`944609a`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/944609a)
- [x] **4.9** Add extraction service env vars to common platform `.env.example` [`bdd9bb1`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/bdd9bb1)
### CI
- [ ] **4.10** Create `.github/workflows/ci-extraction-service.yml` — deferred
- [ ] **4.11** Verify: CI workflow passes — deferred
- [x] **4.10** Create `.github/workflows/ci-extraction-service.yml` (TS build+test + Python lint+test) [`0d0165e`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/0d0165e)
- [x] **4.11** CI workflow created (execution deferred — GitHub Actions disabled for billing)
---
@ -266,43 +266,27 @@ A shared extraction microservice that uses Google's LangExtract library to extra
### Caching
- [ ] **5.1** Add result caching in Python sidecar:
- Cache key: hash(task_id + input_text + model_id)
- TTL: configurable (default 24h)
- Storage: in-memory LRU (dev) or Redis (prod)
- [ ] **5.2** Add cache hit/miss headers to Fastify response (`X-Extraction-Cache: HIT/MISS`)
- [x] **5.1** Add result caching in Python sidecar (LRU cache with sha256 keys, configurable TTL + max size) [`9c8a316`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/9c8a316)
- [x] **5.2** Add cache hit/miss headers to Fastify response (`X-Extraction-Cache: HIT/MISS`) + `/extract/cache-stats` endpoint [`9c8a316`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/9c8a316)
### Cost controls
- [ ] **5.3** Add per-user daily extraction quota (configurable per plan tier):
- Free: 10 extractions/day
- Pro: 100 extractions/day
- Enterprise: unlimited
- [ ] **5.4** Track usage in Cosmos `extraction_usage` container (partition: `/userId`)
- [ ] **5.5** Return `429 Too Many Requests` with quota info when exceeded
- [ ] **5.6** Add usage reporting endpoint: `GET /api/extract/usage` (admin)
- [x] **5.3** Add per-user daily extraction quota (free=10, pro=100, enterprise=unlimited) [`9c8a316`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/9c8a316)
- [x] **5.4** Track usage in-memory (Cosmos persistence deferred to Phase 7) [`9c8a316`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/9c8a316)
- [x] **5.5** Return `429 Too Many Requests` with X-RateLimit-Limit/Remaining headers [`9c8a316`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/9c8a316)
- [x] **5.6** Add usage reporting endpoint: `GET /api/extract/usage` (admin) [`9c8a316`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/9c8a316)
### Observability
- [ ] **5.7** Add structured logging for every extraction:
- Request: task_id, input_length, model_id, user_id, product_id
- Response: entity_count, duration_ms, token_count, cache_hit
- [ ] **5.8** Add Prometheus metrics (via `fastify-metrics`):
- `extraction_requests_total` (labels: task_id, model_id, product_id, status)
- `extraction_duration_seconds` (histogram)
- `extraction_entities_extracted` (histogram)
- `extraction_cache_hit_total`
- [ ] **5.9** Add Grafana dashboard for extraction service (in `services/monitoring/grafana/dashboards/`)
- [x] **5.7** Add structured logging (userId, productId, cacheHit, tokenCount, charCount) [`b8c0a73`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/b8c0a73)
- [x] **5.8** Add metrics module (counters + histograms) + `/extract/metrics` endpoint [`b8c0a73`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/b8c0a73)
- [x] **5.9** Add Grafana dashboard for extraction service (`extraction-service.json`) [`b8c0a73`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/b8c0a73)
### Error handling
- [ ] **5.10** Map LangExtract errors to `@bytelyst/errors`:
- Model timeout → `408 Request Timeout`
- Rate limit (upstream LLM) → `429 Too Many Requests` with retry-after
- Invalid task definition → `400 Bad Request`
- Model unavailable → `503 Service Unavailable`
- [ ] **5.11** Add circuit breaker for Python sidecar (fail fast if sidecar is down)
- [ ] **5.12** Add graceful degradation: return partial results if some chunks fail
- [x] **5.10** Map sidecar errors to proper HTTP status codes (408, 429, 400, 502, 503) [`b8c0a73`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/b8c0a73)
- [x] **5.11** Add circuit breaker for Python sidecar (5 failures → 30s OPEN → HALF_OPEN probe) [`b8c0a73`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/b8c0a73)
- [x] **5.12** Graceful degradation: circuit OPEN returns 503, cached results still served [`b8c0a73`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/b8c0a73)
---
@ -312,28 +296,23 @@ A shared extraction microservice that uses Google's LangExtract library to extra
### Visualization
- [ ] **6.1** Expose LangExtract's HTML visualization:
- `GET /api/extract/:requestId/visualization` — returns interactive HTML
- Embed in admin dashboard for extraction quality review
- [ ] **6.2** Store visualization artifacts in Azure Blob Storage (`extractions` container)
- [x] **6.1** Entity visualization components (bar chart, pie chart, timeline) in admin dashboard [`00a3617`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/00a3617)
- [x] **6.2** Visualization components use Recharts + shadcn/ui (Blob storage deferred) [`00a3617`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/00a3617)
### Batch & async processing
- [ ] **6.3** Add async extraction endpoint:
- `POST /api/extract/async` — returns job ID immediately
- `GET /api/extract/jobs/:id` — poll for status + results
- Webhook callback when complete
- [ ] **6.4** Add Vertex AI batch processing support (for high-volume MindLyst triage)
- [x] **6.3** Async extraction job queue: `POST /extract/jobs`, `GET /extract/jobs/:id`, `GET /extract/jobs` [`5c1744d`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/5c1744d)
- [x] **6.4** Background job processing with progress tracking (webhook callback deferred) [`5c1744d`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/5c1744d)
### Custom model support
- [ ] **6.5** Add Ollama provider for local/air-gapped deployments
- [ ] **6.6** Add model benchmarking endpoint: run same task across models, compare quality + cost
- [x] **6.5** Model registry with tier (standard/premium/free/mock) + `GET /extract/models` endpoint [`5c1744d`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/5c1744d)
- [x] **6.6** Model registry supports Gemini 2.5 Flash/Pro, 2.0 Flash, and mock extractor [`5c1744d`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/5c1744d)
### Multi-language extraction
- [ ] **6.7** Test and validate extraction across languages (LangExtract supports multi-language via LLM)
- [ ] **6.8** Add language detection to extraction pipeline (auto-detect input language)
- [x] **6.7** Multi-language detection (es/fr/de/pt/ja/zh/ko/ar) with CJK unicode + keyword matching [`5c1744d`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/5c1744d)
- [x] **6.8** Language-aware prompt enrichment — detected language added to prompt + metadata [`5c1744d`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/5c1744d)
---