Deprecated Features and Migration Guide

Overview

This document tracks deprecated features, outdated practices, and migration paths in the Aitana codebase. It serves as a reference for what we “don’t do anymore” and what to use instead.

Currently Deprecated

1. Flask-Only Backend (Migrating to FastAPI)

Status: In Migration (Parallel Running)

What’s Deprecated:

  • Pure Flask endpoints without async support
  • Flask-specific request handling patterns
  • Synchronous-only streaming

Current State:

  • Both Flask (app.py) and FastAPI (app_fastapi.py) run in parallel
  • Production still uses Flask
  • FastAPI has feature parity for most endpoints

Migration Path:

2. MCP stdio Compatibility Layer

Status: Temporary (Awaiting Upstream Fix)

What’s Deprecated:

  • The mcp_stdio_compat.py compatibility wrapper

Why:

When Fixed:

  • Use simpler mcp_stdio.py directly
  • Remove compatibility wrapper code

3. Manual Tool Orchestration

Status: Replaced

What’s Deprecated:

  • Manual tool selection in first_impression
  • Hard-coded tool routing logic

What to Use Instead:

  • Automated tool orchestration via tool_orchestrator.py
  • MCP tool registration with VACRoutesFastAPI
  • Dynamic tool discovery

4. check_and_display_thinking() in Production

Status: Deprecated for Performance

What’s Deprecated:

await check_and_display_thinking("Processing...", callback)

Why:

  • Adds 1-4 seconds latency per call
  • Significantly impacts first-token time

What to Use Instead:

# Only in debug mode
if DEBUG_MODE:
    await check_and_display_thinking("Processing...", callback)

Removed Features

1. Agent Tools in MCP

What Was Removed:

  • document-search agent
  • code-execution agent
  • assistant-calling agent

Why:

  • Not yet fully functional in backend
  • Require additional infrastructure

Current Status:

  • Removed from MCP tool registry
  • May be re-added when fully implemented

2. Individual AI Search Tool

What Was Removed:

  • Standalone ai_search tool in MCP

What to Use Instead:

  • ai_search with multiple searches parameter
  • Always use parallel search for better coverage

Example:

# OLD (removed)
await ai_search(question="query")

# NEW (use this)
await ai_search(searches=[
    {"question": "query 1"},
    {"question": "query 2 variation"}
])

Outdated Practices

1. Firebase Emulators as Default

What’s Outdated:

  • Assuming Firebase emulators are always running
  • Default npm run dev with emulators

Current Practice:

  • Use cloud Firebase by default
  • Emulators only for specific local testing
  • Use aitana server start for managed startup

2. Global Python/Pip in Backend

What’s Outdated:

python -m pytest
pip install package

Current Practice:

cd backend
source .venv/bin/activate
uv run pytest
uv add package

3. Sequential Tool Calls

What’s Outdated:

  • Running tools one at a time
  • Waiting for each tool to complete

Current Practice:

  • Batch tool calls in parallel
  • Use asyncio.gather() for multiple operations
  • Especially for search operations

What’s Outdated:

  • Multiple files for single feature (e.g., TOOL_CONFIRMATION_FLOW.md, TOOL_CONFIRMATION_TESTING.md, TOOL_CONFIRMATION_USAGE.md)

Current Practice:

  • Single comprehensive file per feature
  • Use table of contents for navigation
  • Keep related content together

Migration Timelines

Near-term (Q1 2025)

  • Complete FastAPI migration
  • Remove Flask endpoints
  • Resolve MCP stdio compatibility issue

Medium-term (Q2 2025)

  • Implement agent tools fully
  • Migrate all tests to parallel batches
  • Complete Firebase emulator deprecation

Long-term

  • Full async/await throughout backend
  • WebSocket support for real-time features
  • GraphQL API layer

Checking for Deprecated Code

Automated Checks

# Check for deprecated patterns
grep -r "check_and_display_thinking" backend/ --include="*.py" | grep -v "if DEBUG"

# Find Flask-only patterns
grep -r "request.json" backend/ --include="*.py"

# Find synchronous patterns that should be async
grep -r "def.*stream" backend/ --include="*.py" | grep -v "async def"

Manual Review Points

  1. New Features: Should target FastAPI, not Flask
  2. Tool Implementations: Should support MCP registration
  3. Test Files: Should be in appropriate batch folders
  4. Documentation: Should be consolidated, not fragmented

How to Handle Deprecated Features

For Developers

  1. Check this document before implementing new features
  2. Use current practices even if old code exists
  3. Flag deprecated code when encountered
  4. Don’t remove deprecated code without migration plan

For Code Reviews

  1. Block new deprecated patterns in PRs
  2. Suggest current alternatives
  3. Update this document when deprecating features
  4. Add migration paths for deprecated features

For Documentation

  1. Mark deprecated sections clearly
  2. Provide migration guides
  3. Update examples to use current practices
  4. Consolidate related docs when updating

Deprecation Process

Adding a Deprecation

  1. Add entry to this document
  2. Mark code with deprecation comments: 
    # DEPRECATED: Use new_function() instead
# Will be removed in version X.Y
  3. Log deprecation warnings if appropriate
  4. Create migration guide

Removing Deprecated Features

  1. Ensure migration path exists
  2. Check no production dependencies
  3. Remove code and tests
  4. Update documentation
  5. Add to “Removed Features” section