tatlock/CLEANUP_TODO.md

Cleanup Todo: Chat Completions API Wrapper

Status: CHANGED - Chat Completions is now a wrapper, not legacy code

New Architecture (As of 2025-12-06)

Chat Completions API is now a compatibility wrapper around Responses API:

• Maintains single source of truth (Responses API)
• Converts Responses output to Chat Completions format
• Embeds reasoning in <think> tags for Open WebUI
• Provides backward compatibility

When to Consider Cleanup

Only remove Chat Completions wrapper if ALL of these conditions are met:

1. ✅ Open WebUI natively supports Responses API
2. ✅ All other consumers migrated to /v1/responses
3. ✅ No tools/clients require /v1/chat/completions
4. ✅ Team consensus on removal

Current Status: KEEP - Provides essential compatibility for Open WebUI

---

Optional Removal Checklist

Phase 1: Verify All Consumers Migrated

• Open WebUI using /v1/responses natively
• No external tools using /v1/chat/completions
• Check server logs for chat completions usage
• Confirm with team/users

Phase 2: Deprecation Period

• Add deprecation notice to /v1/chat/completions docs
• Update OpenAPI/Swagger docs with deprecation warning
• Log deprecation warnings on chat completions usage
• Maintain for at least one version cycle

Phase 3: Code Removal (If Approved)

Remove Chat Domain

• Delete src/chat/ directory
  • src/chat/router.py
  • src/chat/service.py
  • src/chat/schemas.py
  • src/chat/constants.py
  • Keep src/chat/__init__.py if needed for imports

Update Main Application

• Edit src/main.py
  • Remove from src.chat.router import router as chat_router
  • Remove app.include_router(chat_router, prefix=config.API_PREFIX)

Remove Tests

• Delete tests/chat/ directory
• Remove chat fixtures from tests/conftest.py

Phase 4: Documentation Updates

• Update README.md

  • Remove /v1/chat/completions examples
  • Mark as "Responses API only"
  • Add migration guide link

• Update CHANGELOG.md

  ## [Unreleased]
  
  ### Removed
  - Chat Completions API wrapper (deprecated in v0.X.0)
  - All clients must now use POST /v1/responses
  
  ### Migration
  - See MIGRATION.md for Responses API format
  

• Create MIGRATION.md

  • Show before/after examples
  • Explain <think> tags vs proper reasoning items
  • Conversion guide

---

Current Recommended Action

DO NOT REMOVE - The Chat Completions wrapper serves these purposes:

1. Open WebUI Compatibility - Provides <think> tag format
2. Backward Compatibility - Supports existing clients
3. Migration Path - Smooth transition to Responses API
4. Minimal Cost - Thin wrapper, low maintenance

Documentation Instead of Removal

Update documentation to clarify architecture:

• Chat Completions is a wrapper around Responses API
• Document wrapper behavior in README.md
• Explain <think> tag conversion in AGENTS.md
• Note single source of truth (Responses API)

---

Alternative: Keep as Compatibility Layer

Recommended approach: Keep Chat Completions as permanent compatibility layer

Benefits

• ✅ Supports multiple client types
• ✅ Single codebase maintains both formats
• ✅ No breaking changes for users
• ✅ Minimal maintenance burden

Maintenance

• Update wrapper when Responses API changes
• Keep tests for both endpoints
• Document as compatibility layer
• Monitor usage metrics

---

Git Commit (If Documenting, Not Removing)

git add -A
git commit -m "Document Chat Completions as Responses API wrapper

Update documentation to clarify that Chat Completions endpoint is a
compatibility wrapper around Responses API, not legacy code.

Architecture:
- Single source of truth: Responses API
- Chat Completions wraps Responses API
- Converts reasoning to <think> tags for Open WebUI
- Maintains backward compatibility

Documentation Updates:
- README.md: Explain wrapper architecture
- AGENTS.md: Document conversion behavior
- CLEANUP_TODO.md: Update removal guidance

Status: Chat Completions is a supported compatibility layer

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---

Decision Criteria

Ask these questions before removing:

1. Is anyone using /v1/chat/completions?

   • Check server logs
   • Survey users/team
   • Monitor for 30+ days

2. Does Open WebUI support Responses API natively?

   • Version with native support released?
   • Tested and verified working?
   • Migration path clear?

3. Is there value in multiple formats?

   • Some clients prefer Chat Completions
   • Easier integration for simple use cases
   • Lower barrier to entry

4. What's the maintenance cost?

   • Currently: LOW (thin wrapper)
   • If removed: Users must update clients
   • Cost/benefit analysis

---

Conclusion

Current Recommendation: KEEP Chat Completions wrapper

• Provides value (Open WebUI compatibility)
• Low maintenance cost
• Enables smooth migration
• No compelling reason to remove

Revisit when:

• Open WebUI natively supports Responses API
• Usage metrics show zero chat completions traffic
• Team decides compatibility layer not needed

---

Notes

• This replaces the original "remove chat completions" plan
• Architecture has evolved: wrapper is intentional, not legacy
• Removal is now optional and conditional
• Focus on documentation, not deletion