llama-stack-mirror/MYPY_REMEDIATION_PLAN.md

MyPy Error Remediation Plan

Summary

After removing all mypy suppressions (except strong_typing/auxiliary.py), we have:

• Total Errors: 1,200 errors
• Total Files: 117 files
• Suggested PRs: 17 stacked PRs

Top Error Types

Error Type	Count	Description
union-attr	324	Accessing attributes on Optional/Union types without None checks
arg-type	270	Function argument type mismatches
assignment	132	Variable assignment type mismatches
attr-defined	121	Accessing undefined attributes on objects
no-any-return	108	Functions returning 'Any' instead of specific types
return-value	36	Return type doesn't match function signature
call-arg	32	Wrong arguments passed to function calls
var-annotated	29	Variables missing type annotations
override	22	Method override signature doesn't match parent

Stacked PR Plan

HIGH Priority (Do First)

PR1: Core Routing Tables

• Errors: 163 | Files: 8 | Complexity: MEDIUM
• Main errors: union-attr(81), arg-type(42), no-any-return(25)
• Description: Fix routing tables (models, shields, vector_stores, common)
• Top files:
  • core/routing_tables/common.py (90 errors)
  • core/routing_tables/models.py (28 errors)
  • core/routing_tables/vector_stores.py (26 errors)
• Why first: Foundation for the routing system, affects other PRs

PR2: Core Routers

• Errors: 80 | Files: 7 | Complexity: MEDIUM
• Main errors: no-any-return(34), attr-defined(16), union-attr(12)
• Description: Fix core router implementations (inference, vector_io, safety)
• Top files:
  • core/routers/inference.py (29 errors)
  • core/routers/vector_io.py (28 errors)
  • core/routers/safety.py (9 errors)
• Depends on: PR1 (uses routing tables)

PR3: OpenAI Compatibility Layer

• Errors: 112 | Files: 2 | Complexity: HIGH
• Main errors: arg-type(37), union-attr(23), assignment(17)
• Description: Fix OpenAI/LiteLLM integration utils
• Top files:
  • providers/utils/inference/openai_compat.py (88 errors)
  • providers/utils/inference/litellm_openai_mixin.py (24 errors)
• Independent: Can be done in parallel with PR1-2

PR4: Meta Reference Agents

• Errors: 280 | Files: 9 | Complexity: HIGH
• Main errors: union-attr(128), arg-type(78), attr-defined(27)
• Description: Fix meta reference agent implementation
• Top files:
  • providers/inline/agents/meta_reference/agent_instance.py (81 errors)
  • providers/inline/agents/meta_reference/responses/openai_responses.py (76 errors)
  • providers/inline/agents/meta_reference/responses/tool_executor.py (45 errors)
• Independent: Can be done in parallel

---

MEDIUM Priority (Do After HIGH)

PR5: Llama Models

• Errors: 123 | Files: 15 | Complexity: HIGH
• Main errors: assignment(31), attr-defined(26), no-any-return(13)
• Description: Fix llama model implementations (llama3, llama4, multimodal)
• Top files:
  • models/llama/llama3/multimodal/model.py (27 errors)
  • models/llama/llama3/generation.py (24 errors)

PR6: Provider Utils - Inference

• Errors: 41 | Files: 3 | Complexity: MEDIUM
• Description: Fix provider inference utilities (prompt_adapter, model_registry, embedding_mixin)

PR7: Provider Utils - Storage

• Errors: 36 | Files: 4 | Complexity: MEDIUM
• Description: Fix storage utilities (kvstore, memory, sqlstore)

PR8: Provider Utils - Other

• Errors: 28 | Files: 4 | Complexity: MEDIUM
• Description: Fix other provider utils (bedrock, telemetry, tools, scoring)

PR9: Inline Providers - Eval

• Errors: 53 | Files: 1 | Complexity: MEDIUM
• Description: Fix inline eval provider

PR10: Inline Providers - Safety

• Errors: 21 | Files: 4 | Complexity: MEDIUM
• Description: Fix inline safety providers (llama_guard, code_scanner)

PR12: Inline Providers - Inference & Post-Training

• Errors: 10 | Files: 2 | Complexity: HIGH
• Description: Fix inline inference and post-training providers

PR14: Remote Providers - Inference

• Errors: 67 | Files: 12 | Complexity: MEDIUM
• Description: Fix remote inference providers (bedrock, nvidia, tgi, together, etc.)

PR17: Core - Remaining

• Errors: 43 | Files: 7 | Complexity: MEDIUM
• Description: Fix remaining core modules (server, client, build, utils, store)

---

LOW Priority (Can be parallelized or done last)

PR11: Inline Providers - Scoring

• Errors: 27 | Files: 10 | Complexity: MEDIUM
• Description: Fix inline scoring providers (basic, braintrust, llm_as_judge)

PR13: Inline Providers - Other

• Errors: 10 | Files: 2 | Complexity: LOW
• Description: Fix other inline providers (datasetio, vector_io)

PR15: Remote Providers - Vector IO

• Errors: 51 | Files: 11 | Complexity: MEDIUM
• Description: Fix remote vector_io providers (chroma, qdrant, weaviate, pgvector, milvus)

PR16: Remote Providers - Other

• Errors: 49 | Files: 15 | Complexity: MEDIUM
• Description: Fix other remote providers (safety, tool_runtime, post_training, etc.)

---

Recommended Execution Strategy

Phase 1: Foundation (Week 1)

1. PR1: Core Routing Tables (163 errors) - Start here
2. PR2: Core Routers (80 errors) - Stack on PR1

Phase 2: High-Value Infrastructure (Week 1-2)

3. PR3: OpenAI Compatibility Layer (112 errors) - Parallel with Phase 1
4. PR4: Meta Reference Agents (280 errors) - Parallel with Phase 1

Phase 3: Core Components (Week 2-3)

• PR5: Llama Models (123 errors)
• PR17: Core - Remaining (43 errors)
• Can be done in parallel

Phase 4: Provider Utilities (Week 3-4)

• PR6-10: Provider Utils & Inline Providers
• Can be done in parallel by different developers

Phase 5: Remote Providers (Week 4-5)

• PR14-16: Remote provider implementations
• Can be done in parallel

Phase 6: Cleanup (Week 5)

• PR11, PR13: Low priority items

Commands

# Run mypy with full type checking
uv run --group dev --group type_checking mypy

# Run mypy on specific module
uv run --group dev --group type_checking mypy src/llama_stack/core/routing_tables/

# See detailed errors for a file
uv run --group dev --group type_checking mypy src/llama_stack/core/routing_tables/common.py

Notes

• All PRs should include tests where applicable
• Each PR should pass uv run --group dev --group type_checking mypy on its changed files
• Consider adding --check-untyped-defs flag for even stricter checking in the future
• Some errors may cascade - fixing one file might fix errors in dependent files