Document the difference between /api and /ai_proxy_core directories

[ebowwa]

Problem

The project structure contains two main directories that serve different purposes, but this distinction is not documented anywhere:

• /ai_proxy_core - The core Python library that gets published to PyPI
• /api - The FastAPI web service layer that wraps the library

This causes confusion for contributors and users who don't understand why there are two seemingly similar directories with completion handlers.

Current Structure

ai-proxy-core/
├── ai_proxy_core/          # Core library (pip package)
│   ├── __init__.py
│   ├── completion_client.py
│   ├── models.py
│   └── providers/
│       ├── openai.py
│       ├── google.py
│       └── ollama.py
│
├── api/                     # FastAPI web service
│   ├── completions.py      # HTTP endpoints
│   └── gemini_live.py      # WebSocket endpoints
│
├── main.py                 # FastAPI app entry point
├── setup.py                # Package configuration
└── README.md

Proposed Solution

Add a "Project Structure" section to the README that explains:

1. /ai_proxy_core - The reusable Python library

   • Can be installed via pip: pip install ai-proxy-core
   • Used programmatically in Python code
   • Contains all the core logic and provider implementations
   • Example: from ai_proxy_core import CompletionClient

2. /api - The REST API layer

   • FastAPI routes that expose the library over HTTP
   • Provides OpenAI-compatible endpoints
   • Enables non-Python clients to use the service
   • Runs as a web server: python main.py

3. Architecture flow:

   HTTP Request → FastAPI (/api) → Core Library (/ai_proxy_core) → AI Providers
   

Benefits of Documentation

• Reduces contributor confusion
• Helps users understand how to use the project (as a library vs as a service)
• Makes the dual-purpose nature of the project clear
• Improves onboarding for new developers

Related Files to Update

• README.md - Add "Project Structure" section
• Contributing guide (if exists) - Explain where to make changes
• Examples - Show both library and API usage patterns