This repository primarily documents and validates a package migration for Harper. The goal of this change is to modernize dependencies, reduce maintenance risk, and keep the application aligned with supported SDKs—without changing user‑visible behavior.
TL;DR: Harper was migrated from the deprecated
google.generativeaipackage to the moderngoogle.genaiSDK. All imports, API calls, and dependencies were updated while preserving functionality, routes, and behavior.
- Deprecation risk:
google.generativeaiis deprecated and no longer recommended. - Forward compatibility:
google.genaiis the supported SDK going forward. - Maintenance & security: Supported SDKs receive fixes, improvements, and security updates.
- No feature churn: The migration intentionally avoids product or UX changes.
- Replaced all
google.generativeaiimports withgoogle.genai - Updated client initialization and request patterns to match the new SDK
- Adjusted dependency versions in
requirements.txt - Verified all AI-backed routes continue to work as before
- Application behavior and responses
- Flask routes and URL structure
- Templates, CSS, and frontend behavior
- Test coverage and CI expectations
- Deployment model (Vercel / Docker compatible)
| Area | Before | After |
|---|---|---|
| Gemini SDK | google.generativeai |
google.genai |
| Support status | Deprecated | Actively supported |
| API surface | Legacy | Current / stable |
| Behavior | — | Unchanged |
The migration was performed as a mechanical, low‑risk refactor, focusing on correctness and parity.
To ensure migration safety:
- All existing unit tests pass (
pytest) - End‑to‑end Playwright tests pass
- Manual verification of AI search, verification flow, and static routes
- No runtime warnings or SDK deprecation notices
This confirms functional equivalence before and after the migration.
Minimal documentation relevant to the migration and maintenance:
- API.md — API endpoints and usage examples
- docs/development/README.md — Development workflow
- docs/development/hooks/README.md — Git hooks overview
- docs/development/hooks/ruff.md — Ruff configuration
- docs/development/hooks/pre-commit.md — Pre‑commit hooks
Harper remains a minimal Flask web application for AI‑powered media exploration.
path/app.py: Flask app and routes, now usinggoogle.genaitemplates/: Jinja templates for all static and dynamic pagesstatic/css/style.css: Theme system and responsive stylesrequirements.txt: Updated, minimal dependenciestests/: Unit tests validating route behavior
The migration does not introduce architectural changes.
- Python 3.8+
- Node.js 16+
- npm
git clone https://github.com/bniladridas/path.git
cd path
pip install -r requirements.txt
npm install
npx playwright installRun commands from the project root directory:
# Set your API key and run the app
GEMINI_API_KEY=your-key python run.pypytest
npm testAPI key sanity check:
curl "https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_API_KEY"While outside the core package migration, the repository also includes a completed Jinja template refactor:
- 800+ lines of hardcoded HTML removed from JavaScript
- Content moved to proper Jinja templates
- AJAX loading via Flask routes
- Improved security, maintainability, and separation of concerns
This refactor is orthogonal to the SDK migration and can be reviewed independently.
This migration follows conventional commits to keep history reviewable and safe for backports.
Example:
refactor: migrate gemini sdk to google.genai
This change is:
- ✅ Backward‑compatible
- ✅ Behavior‑preserving
- ✅ Safe to roll back
- ✅ Required for long‑term maintenance
No product decisions were made as part of this work—only dependency hygiene.
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.