cinematch 0.1.0__tar.gz

cinematch-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: cinematch
+Version: 0.1.0
+Summary: A personalized movie and series recommendation web app
+Author-email: bkallash <bayankallash@gmail.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: openai>=1.40.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: twine>=6.1.0; extra == "dev"
+
+# CineMatch — AI-Powered Movie & Series Suggestion App
+
+A modern, cinephile-grade recommendation engine built in Python, featuring a living **Taste Dossier**, hybrid vector RAG retrieval, and an interactive dark-mode web UI.
+
+---
+
+## Key Features
+
+1. **💬 CineMatch Concierge (Assistant)**:
+   - Natural language vibe matching (e.g. *"Suggest a romantic movie like La La Land with bittersweet melancholia"*, *"Cozy 90s holiday comedy"*).
+   - Multi-turn conversational flow powered by OpenRouter **GPT-4o**.
+   - Dual-layer recommendation pipeline: fast in-process SQLite vector retrieval + LLM reranking against your living **Taste Dossier**.
+   - Surfaces personalized reasoning cards with "Why You'll Love It" callouts and highlights matching titles from your own Watchlist.
+
+2. **🎴 Famous Titles Rating Deck**:
+   - Fast-fire card queue of widely recognized movies and TV series with posters, trailers, and synopses.
+   - Non-neutral **1 to 6 rating scale** (1–3 = Disliked/Flawed, 4–6 = Good/Masterpiece).
+   - Adaptive **Aspect Tags** (concise single-concept tags like `Visuals`, `Pacing`, `Ending`, `Soundtrack`, `Plot Holes`, `Cliche`).
+   - Quick **"Haven't Seen (Skip)"** and **"Want to Watch"** action buttons.
+
+3. **🔍 Search & Rate**:
+   - Real-time debounced search bar connecting local SQLite storage with live TMDB (The Movie Database).
+   - Log 1–6 ratings and micro-notes on any title in cinema history.
+
+4. **📚 My Library & Taste Dossier**:
+   - **Ratings**: Browse and filter your rated titles by score, media type, and aspect tags.
+   - **Watchlist**: Manage everything marked "Want to Watch".
+   - **Taste Dossier**: Transparently inspect what the AI has synthesized about your cinematic DNA (Core Loves, Deal-Breakers, Creator Affinities, and Narrative Tropes), with a one-click re-synthesis trigger.
+
+---
+
+## Quickstart Guide
+
+### 1. Activate the Virtual Environment
+
+```powershell
+cd "D:\code Projects\SPOC\movie-suggestion"
+.\venv\Scripts\activate
+```
+
+### 2. Configure Your API Keys in `.env`
+
+Copy `.env.example` to `.env` (or edit existing `.env`):
+
+```env
+# OpenRouter Configuration (for GPT-4o and Text Embeddings)
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_MODEL=openai/gpt-4o
+
+# TMDB API Key (Free from https://www.themoviedb.org/settings/api)
+TMDB_API_KEY=your_tmdb_api_key_here
+
+# Embeddings
+EMBEDDING_PROVIDER=openrouter
+EMBEDDING_MODEL=openai/text-embedding-3-small
+```
+
+> **Note**: Even before adding API keys, CineMatch runs fully with its pre-bundled catalog of famous titles and deterministic vector fallbacks.
+
+Set `EMBEDDING_PROVIDER=local` for offline token-based text matching without a model download. Cloud embeddings provide richer semantic matching. Each stored vector tracks its provider, model, and dimension; startup rebuilds incompatible or older unversioned vectors in batches of 64. With OpenRouter configured, this rebuild makes billable embedding requests. Failed batches are retried at the next startup.
+
+### 3. Run the Web Application
+
+```powershell
+.\venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000
+```
+
+Open your browser at: **[http://localhost:8000](http://localhost:8000)**
+
+---
+
+## Install from PyPI
+
+Install and run CineMatch from any directory:
+
+```powershell
+python -m pip install cinematch
+cinematch
+```
+
+On the first run, CineMatch prompts for:
+
+1. Your OpenRouter API key. Create one at [OpenRouter Keys](https://openrouter.ai/settings/keys). The key is entered using a hidden password prompt.
+2. An OpenRouter model identifier, such as `openai/gpt-4o`. Browse the available identifiers on the [OpenRouter Models](https://openrouter.ai/models) page.
+
+```text
+CineMatch first-run setup
+Create an API key at https://openrouter.ai/settings/keys
+OpenRouter API key (input is hidden):
+OpenRouter model [openai/gpt-4o]:
+```
+
+The configuration is saved in CineMatch's operating-system user data directory and reused on later runs. The SQLite database is stored there as well. To change the API key or model later, run:
+
+```powershell
+cinematch --configure
+```
+
+You can also create a `.env` file in the directory where you run CineMatch. This local configuration takes precedence:
+
+```env
+OPENROUTER_API_KEY=pypi_user_openrouter_key
+OPENROUTER_MODEL=openai/gpt-4o
+```
+
+Run `cinematch --help` to select a host, port, or custom data directory.
+
+### Build and publish a release
+
+```powershell
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+PyPI accepts an API token as the username `__token__`; use the full token, including its `pypi-` prefix, as the password. Increase the version in `pyproject.toml` before every later release because PyPI release files cannot be replaced.
+
+---
+
+## Architecture & Design Documents
+
+All architectural choices and domain terminology are formally documented:
+- [`CONTEXT.md`](./CONTEXT.md) — Ubiquitous language and domain glossary.
+- [`docs/adr/0001-hybrid-rag-taste-dossier.md`](./docs/adr/0001-hybrid-rag-taste-dossier.md) — Dual-layer RAG & Taste Dossier architecture.
+- [`docs/adr/0002-six-point-forced-choice-rating-scale.md`](./docs/adr/0002-six-point-forced-choice-rating-scale.md) — 1–6 discrete forced-choice rating scale.
+- [`docs/adr/0003-hybrid-catalog-orchestrator.md`](./docs/adr/0003-hybrid-catalog-orchestrator.md) — Local vector search + dynamic TMDB discovery fallback.
+- [`docs/adr/0004-in-process-sqlite-vectors.md`](./docs/adr/0004-in-process-sqlite-vectors.md) — Zero-dependency in-process SQLite BLOB vector storage.
+- [`docs/adr/0005-dual-source-embedding-strategy.md`](./docs/adr/0005-dual-source-embedding-strategy.md) — OpenRouter with offline local embedding toggle.
+- [`docs/adr/0006-bundled-curated-starter-catalog.md`](./docs/adr/0006-bundled-curated-starter-catalog.md) — Bundled curated starter dataset.
+- [`docs/adr/0007-compatible-embeddings.md`](./docs/adr/0007-compatible-embeddings.md) — Embedding compatibility, batched rebuilds, and lightweight local matching.
+
+---
+
+## Verification Tests
+
+Install test dependencies and run the suite. Tests use a temporary database and disable external APIs, leaving your library untouched:
+
+```powershell
+.\venv\Scripts\python.exe -m pip install -r requirements-dev.txt
+.\venv\Scripts\python.exe -m pytest -q
+```

cinematch-0.1.0/README.md

@@ -0,0 +1,143 @@
+# CineMatch — AI-Powered Movie & Series Suggestion App
+
+A modern, cinephile-grade recommendation engine built in Python, featuring a living **Taste Dossier**, hybrid vector RAG retrieval, and an interactive dark-mode web UI.
+
+---
+
+## Key Features
+
+1. **💬 CineMatch Concierge (Assistant)**:
+   - Natural language vibe matching (e.g. *"Suggest a romantic movie like La La Land with bittersweet melancholia"*, *"Cozy 90s holiday comedy"*).
+   - Multi-turn conversational flow powered by OpenRouter **GPT-4o**.
+   - Dual-layer recommendation pipeline: fast in-process SQLite vector retrieval + LLM reranking against your living **Taste Dossier**.
+   - Surfaces personalized reasoning cards with "Why You'll Love It" callouts and highlights matching titles from your own Watchlist.
+
+2. **🎴 Famous Titles Rating Deck**:
+   - Fast-fire card queue of widely recognized movies and TV series with posters, trailers, and synopses.
+   - Non-neutral **1 to 6 rating scale** (1–3 = Disliked/Flawed, 4–6 = Good/Masterpiece).
+   - Adaptive **Aspect Tags** (concise single-concept tags like `Visuals`, `Pacing`, `Ending`, `Soundtrack`, `Plot Holes`, `Cliche`).
+   - Quick **"Haven't Seen (Skip)"** and **"Want to Watch"** action buttons.
+
+3. **🔍 Search & Rate**:
+   - Real-time debounced search bar connecting local SQLite storage with live TMDB (The Movie Database).
+   - Log 1–6 ratings and micro-notes on any title in cinema history.
+
+4. **📚 My Library & Taste Dossier**:
+   - **Ratings**: Browse and filter your rated titles by score, media type, and aspect tags.
+   - **Watchlist**: Manage everything marked "Want to Watch".
+   - **Taste Dossier**: Transparently inspect what the AI has synthesized about your cinematic DNA (Core Loves, Deal-Breakers, Creator Affinities, and Narrative Tropes), with a one-click re-synthesis trigger.
+
+---
+
+## Quickstart Guide
+
+### 1. Activate the Virtual Environment
+
+```powershell
+cd "D:\code Projects\SPOC\movie-suggestion"
+.\venv\Scripts\activate
+```
+
+### 2. Configure Your API Keys in `.env`
+
+Copy `.env.example` to `.env` (or edit existing `.env`):
+
+```env
+# OpenRouter Configuration (for GPT-4o and Text Embeddings)
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_MODEL=openai/gpt-4o
+
+# TMDB API Key (Free from https://www.themoviedb.org/settings/api)
+TMDB_API_KEY=your_tmdb_api_key_here
+
+# Embeddings
+EMBEDDING_PROVIDER=openrouter
+EMBEDDING_MODEL=openai/text-embedding-3-small
+```
+
+> **Note**: Even before adding API keys, CineMatch runs fully with its pre-bundled catalog of famous titles and deterministic vector fallbacks.
+
+Set `EMBEDDING_PROVIDER=local` for offline token-based text matching without a model download. Cloud embeddings provide richer semantic matching. Each stored vector tracks its provider, model, and dimension; startup rebuilds incompatible or older unversioned vectors in batches of 64. With OpenRouter configured, this rebuild makes billable embedding requests. Failed batches are retried at the next startup.
+
+### 3. Run the Web Application
+
+```powershell
+.\venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000
+```
+
+Open your browser at: **[http://localhost:8000](http://localhost:8000)**
+
+---
+
+## Install from PyPI
+
+Install and run CineMatch from any directory:
+
+```powershell
+python -m pip install cinematch
+cinematch
+```
+
+On the first run, CineMatch prompts for:
+
+1. Your OpenRouter API key. Create one at [OpenRouter Keys](https://openrouter.ai/settings/keys). The key is entered using a hidden password prompt.
+2. An OpenRouter model identifier, such as `openai/gpt-4o`. Browse the available identifiers on the [OpenRouter Models](https://openrouter.ai/models) page.
+
+```text
+CineMatch first-run setup
+Create an API key at https://openrouter.ai/settings/keys
+OpenRouter API key (input is hidden):
+OpenRouter model [openai/gpt-4o]:
+```
+
+The configuration is saved in CineMatch's operating-system user data directory and reused on later runs. The SQLite database is stored there as well. To change the API key or model later, run:
+
+```powershell
+cinematch --configure
+```
+
+You can also create a `.env` file in the directory where you run CineMatch. This local configuration takes precedence:
+
+```env
+OPENROUTER_API_KEY=pypi_user_openrouter_key
+OPENROUTER_MODEL=openai/gpt-4o
+```
+
+Run `cinematch --help` to select a host, port, or custom data directory.
+
+### Build and publish a release
+
+```powershell
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+PyPI accepts an API token as the username `__token__`; use the full token, including its `pypi-` prefix, as the password. Increase the version in `pyproject.toml` before every later release because PyPI release files cannot be replaced.
+
+---
+
+## Architecture & Design Documents
+
+All architectural choices and domain terminology are formally documented:
+- [`CONTEXT.md`](./CONTEXT.md) — Ubiquitous language and domain glossary.
+- [`docs/adr/0001-hybrid-rag-taste-dossier.md`](./docs/adr/0001-hybrid-rag-taste-dossier.md) — Dual-layer RAG & Taste Dossier architecture.
+- [`docs/adr/0002-six-point-forced-choice-rating-scale.md`](./docs/adr/0002-six-point-forced-choice-rating-scale.md) — 1–6 discrete forced-choice rating scale.
+- [`docs/adr/0003-hybrid-catalog-orchestrator.md`](./docs/adr/0003-hybrid-catalog-orchestrator.md) — Local vector search + dynamic TMDB discovery fallback.
+- [`docs/adr/0004-in-process-sqlite-vectors.md`](./docs/adr/0004-in-process-sqlite-vectors.md) — Zero-dependency in-process SQLite BLOB vector storage.
+- [`docs/adr/0005-dual-source-embedding-strategy.md`](./docs/adr/0005-dual-source-embedding-strategy.md) — OpenRouter with offline local embedding toggle.
+- [`docs/adr/0006-bundled-curated-starter-catalog.md`](./docs/adr/0006-bundled-curated-starter-catalog.md) — Bundled curated starter dataset.
+- [`docs/adr/0007-compatible-embeddings.md`](./docs/adr/0007-compatible-embeddings.md) — Embedding compatibility, batched rebuilds, and lightweight local matching.
+
+---
+
+## Verification Tests
+
+Install test dependencies and run the suite. Tests use a temporary database and disable external APIs, leaving your library untouched:
+
+```powershell
+.\venv\Scripts\python.exe -m pip install -r requirements-dev.txt
+.\venv\Scripts\python.exe -m pytest -q
+```

cinematch-0.1.0/app/__init__.py

@@ -0,0 +1,2 @@
+# CineMatch Application Package
+__version__ = "0.1.0"

cinematch-0.1.0/app/cli.py

@@ -0,0 +1,97 @@
+"""Command-line entry point for an installed CineMatch application."""
+
+import argparse
+import getpass
+import os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv, set_key
+
+DEFAULT_OPENROUTER_MODEL = "openai/gpt-4o"
+
+
+def default_data_dir() -> Path:
+    if sys.platform == "win32":
+        root = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
+        return Path(root) / "CineMatch" if root else Path.home() / "CineMatch"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "CineMatch"
+    return Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share")) / "cinematch"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run the CineMatch web application.")
+    parser.add_argument("--host", default="127.0.0.1", help="Address to listen on.")
+    parser.add_argument("--port", type=int, help="Port to listen on (default: APP_PORT or 8000).")
+    parser.add_argument("--reload", action="store_true", help="Reload when source files change.")
+    parser.add_argument(
+        "--configure",
+        action="store_true",
+        help="Prompt for the OpenRouter API key and model before starting.",
+    )
+    parser.add_argument(
+        "--data-dir",
+        type=Path,
+        help="Directory for cinematch.db (default: the operating system's user data directory).",
+    )
+    return parser
+
+
+def openrouter_is_configured() -> bool:
+    api_key = os.environ.get("OPENROUTER_API_KEY", "").strip()
+    model = os.environ.get("OPENROUTER_MODEL", "").strip()
+    return bool(api_key and not api_key.startswith("your_") and model)
+
+
+def configure_openrouter(env_path: Path) -> None:
+    if not sys.stdin.isatty():
+        raise SystemExit(
+            "OpenRouter is not configured. Run 'cinematch --configure' in an interactive "
+            "terminal, or set OPENROUTER_API_KEY and OPENROUTER_MODEL."
+        )
+
+    print("\nCineMatch first-run setup")
+    print("Create an API key at https://openrouter.ai/settings/keys")
+    api_key = getpass.getpass("OpenRouter API key (input is hidden): ").strip()
+    if not api_key:
+        raise SystemExit("An OpenRouter API key is required.")
+
+    current_model = os.environ.get("OPENROUTER_MODEL", DEFAULT_OPENROUTER_MODEL)
+    model = input(f"OpenRouter model [{current_model}]: ").strip() or current_model
+
+    env_path.touch(exist_ok=True)
+    set_key(env_path, "OPENROUTER_API_KEY", api_key)
+    set_key(env_path, "OPENROUTER_MODEL", model)
+    os.environ["OPENROUTER_API_KEY"] = api_key
+    os.environ["OPENROUTER_MODEL"] = model
+    print(f"Configuration saved to {env_path}\n")
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    data_dir = args.data_dir or default_data_dir()
+    data_dir.mkdir(parents=True, exist_ok=True)
+    user_env_path = data_dir / ".env"
+
+    # A project-specific .env takes precedence over the saved user configuration.
+    load_dotenv(Path.cwd() / ".env")
+    load_dotenv(user_env_path)
+    if args.configure or not openrouter_is_configured():
+        configure_openrouter(user_env_path)
+
+    os.environ.setdefault("DATABASE_PATH", str(data_dir / "cinematch.db"))
+
+    from app.config import settings
+    import uvicorn
+
+    uvicorn.run(
+        "app.main:app",
+        host=args.host,
+        port=args.port or settings.APP_PORT,
+        reload=args.reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

cinematch-0.1.0/app/config.py

@@ -0,0 +1,38 @@
+import os
+from pathlib import Path
+from typing import Literal
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+class Settings(BaseSettings):
+    # OpenRouter
+    OPENROUTER_API_KEY: str = Field(default="", description="OpenRouter API Key")
+    OPENROUTER_BASE_URL: str = Field(default="https://openrouter.ai/api/v1", description="OpenRouter Base URL")
+    OPENROUTER_MODEL: str = Field(default="openai/gpt-4o", description="Model for reasoning and chat")
+
+    # Embeddings
+    EMBEDDING_PROVIDER: Literal["openrouter", "local"] = "openrouter"
+    EMBEDDING_MODEL: str = Field(default="openai/text-embedding-3-small", description="Model for text embeddings")
+    EMBEDDING_DIM: int = Field(default=1536, gt=0, description="Dimension of embedding vectors")
+
+    # TMDB API
+    TMDB_API_KEY: str = Field(default="", description="The Movie Database API Key")
+    TMDB_BASE_URL: str = Field(default="https://api.themoviedb.org/3", description="TMDB API Base URL")
+    TMDB_IMAGE_BASE_URL: str = Field(default="https://image.tmdb.org/t/p/w500", description="TMDB Poster CDN Base URL")
+
+    # Database
+    DATABASE_PATH: Path = Field(default=BASE_DIR / "cinematch.db", description="Path to SQLite database")
+
+    # App Settings
+    APP_PORT: int = Field(default=8000)
+    DEBUG: bool = Field(default=True)
+
+    model_config = SettingsConfigDict(
+        env_file=BASE_DIR / ".env",
+        env_file_encoding="utf-8",
+        extra="ignore"
+    )
+
+settings = Settings()