# 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
  ```markdown
  ## [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:

- [x] 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)

```bash
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