Migration Guide

Guide for migrating packages to AI Platform standards

Standards to Adopt

Standard Requirement
Python >= 3.12
Build System hatchling
AI Client google-genai (not google-generativeai)
Database SQLAlchemy 2.0+ with ai-platform-shared base

Package Migrations Required

ai-voicememo

Current State:

  • Python: >=3.10
  • Build: setuptools
  • AI: google-generativeai

Migration Steps:

  1. Update pyproject.toml:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
requires-python = ">=3.12"
dependencies = [
    "ai-platform-shared>=1.0.0",
    "google-genai>=1.0.0",  # Replace google-generativeai
    ...
]

[tool.hatch.build.targets.wheel]
packages = ["src/ai_voicememo"]
  1. Update Gemini client imports:
# Old (deprecated)
import google.generativeai as genai
genai.configure(api_key=key)
model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(prompt)

# New
from google import genai
client = genai.Client(api_key=key)
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=prompt
)
  1. Use shared models:
# Old
from .models.project import Project, Person

# New
from ai_platform.shared.models import Project, Person

ai-core

Current State:

  • Python: >=3.10
  • Build: setuptools
  • AI: google-generativeai

Migration Steps:

  1. Update pyproject.toml to use hatchling
  2. Migrate Gemini client in src/ai_core/clients/gemini.py
  3. Add dependency on ai-platform-shared

ai-korrespondenz

Current State:

  • Python: >=3.11
  • Build: hatchling ✓
  • AI: google-generativeai

Migration Steps:

  1. Update Python requirement to >=3.12
  2. Migrate Gemini client usage
  3. Consider using shared models for Person (correspondent)

Deprecated Packages

ai-mail → ai-korrespondenz

ai-mail has been fully integrated into ai-korrespondenz.

Migration:

# Old
from ai_mail.gmail import GmailClient
from ai_mail.thunderbird import ThunderbirdSync

# New
from ai_korrespondenz.sources.gmail import GmailService
from ai_korrespondenz.sources.thunderbird import ThunderbirdService

Action: Move ai-mail to deprecated/ folder.

ai-pdai → ai-core/pdai

ai-pdai functionality is now in ai-core.

Migration:

# Old
from ai_pdai import PDAIDocument

# New
from ai_core.pdai import Document

Action: Move ai-pdai to deprecated/ folder.

ai-apple-documents → ai-korrespondenz

Apple document sources moved to ai-korrespondenz.

Migration:

# Old
from ai_apple_documents import NotesSource

# New
from ai_korrespondenz.sources.notes import NotesService

Action: Move ai-apple-documents to deprecated/ folder.

google-generativeai → google-genai Migration

The google-generativeai package is deprecated. Here’s the migration guide:

Installation Change

# Remove old
pip uninstall google-generativeai

# Install new
pip install google-genai

Import Changes

# Old
import google.generativeai as genai

# New
from google import genai

Client Initialization

# Old
genai.configure(api_key=os.environ["GEMINI_API_KEY"])

# New
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

Content Generation

# Old
model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content("Hello")
text = response.text

# New
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents="Hello"
)
text = response.text

Multimodal (with images)

# Old
model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content([prompt, image])

# New
from google.genai import types

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=[
        types.Content(
            role="user",
            parts=[
                types.Part.from_text(prompt),
                types.Part.from_image(image)
            ]
        )
    ]
)

Streaming

# Old
for chunk in model.generate_content(prompt, stream=True):
    print(chunk.text)

# New
for chunk in client.models.generate_content_stream(
    model='gemini-3.8-flash',
    contents=prompt
):
    print(chunk.text)

Using Shared Infrastructure

Database

from ai_platform.shared.database import Base, TimestampMixin, get_engine

class MyModel(Base, TimestampMixin):
    __tablename__ = 'my_table'
    
    id = Column(Integer, primary_key=True)
    name = Column(String)

# Initialize
engine = get_engine(db_path=Path("./my.db"))
init_db(engine)

Models

from ai_platform.shared.models import Person, Project, PersonRole

person = Person(
    id="inqua_001",
    full_name="Herr Müller",
    role=PersonRole.CLIENT,
    project_id="inqua"
)

Instructions

from ai_platform.shared.instructions import render

prompt = render("classification/voicememo.j2",
    memo_id="20260113",
    title="Meeting Notes",
    projects=my_projects
)

Timeline

  1. Immediate: Document deprecated packages
  2. Week 1: Migrate ai-voicememo to new standards
  3. Week 2: Migrate ai-core
  4. Week 3: Update ai-korrespondenz
  5. Week 4: Move deprecated packages to archive