first commit

Author: brayniverse

.env.example

@@ -0,0 +1,6 @@
+# Wikidata User-Agent (Required by Wikidata API policy)
+WIKIDATA_USER_AGENT=open-cinema-index (your-email@example.com)
+
+# TMDb API Key (Required for fetching posters and other metadata from TMDb)
+TMDB_API_KEY=your_tmdb_api_key_here
+

.github/workflows/lint.yml

@@ -0,0 +1,17 @@
+name: Lint
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install ruff
+        run: pip install ruff
+      - name: Run Ruff
+        run: ruff check .

.github/workflows/pytest.yml

@@ -0,0 +1,25 @@
+name: Pytest
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+    - name: Run pytest
+      run: |
+        pytest

.gitignore

@@ -0,0 +1,25 @@
+# Database
+data/open_cinema_index.db
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# IDEs
+.idea/
+.vscode/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/

DEVELOPMENT.md

@@ -0,0 +1,69 @@
+# Development Guide
+
+This document provides information for developers who want to contribute to the `open-cinema-index` project.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- `pip`
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/project-watchlist/open-cinema-index.git
+   cd open-cinema-index
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install -e .
+   ```
+
+3. Set up environment variables as described in the `README.md`.
+
+## Database Migrations
+
+This project uses [Alembic](https://alembic.sqlalchemy.org/) for database migrations. The database is a SQLite file located at `data/open_cinema_index.db`.
+
+### Running Migrations
+
+To bring your local database up to date with the latest schema, run:
+
+```bash
+alembic upgrade head
+```
+
+### Creating New Migrations
+
+If you make changes to the models in `src/open_cinema_index/models/`, you should generate a new migration script:
+
+```bash
+alembic revision --autogenerate -m "description of changes"
+```
+
+Then, apply the migration as described above.
+
+### Troubleshooting
+
+If migrations fail due to the `data/` directory missing, ensure it exists:
+
+```bash
+mkdir -p data
+```
+
+## Running Tests
+
+Testing is highly recommended for validating model relationships and ensuring data integrity.
+
+1. Install development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+2. Run tests using `pytest`:
+   ```bash
+   pytest
+   ```

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brayniverse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,104 @@
+# Open Cinema Index
+
+*Open Cinema Index (OCI)* is a data ingestion and enrichment pipeline for building a structured, open index of films and related entities. It is designed for research, recommendation engines, and archival purposes. The repository contains scripts to fetch film data from open sources, enrich it with metadata, and prepare it for downstream applications.
+
+It is *not* a recommendation engine, a rating platform, or an editorial system.
+Its sole responsibility is to build a reliable, inspectable index of film knowledge that other systems can depend on.
+
+OCI is designed to treat cinema as it actually exists: messy, disputed, multilingual, and full of partial truths.
+
+## Features
+
+- Fetch films from Wikidata by year and retrieve basic metadata
+- Enrich films with properties such as genre, language, and age ratings
+- Designed for offline processing, production applications consume pre-built datasets
+
+## How OCI Thinks About Films
+
+OCI is built around a few guiding ideas:
+
+- Films are stable entities; facts about them are not
+- Titles, genres, runtimes, and even credits are _claims_, not facts
+- Different sources disagree, and that disagreement is meaningful
+
+Rather than flattening every into a single record, OCI keeps track of:
+
+- who said what
+- when they said it
+- and how confident we are
+
+Ambiguity is preserved, not "cleaned up".
+
+## The Ingestion Pipeline
+
+OCI is structured as a pipeline of explicit, repeatable steps:
+
+```text
+fetch -> normalize -> resolve -> enrich -> export
+```
+
+Each step has a narrow responsibility.
+
+### Fetch
+
+Retrieves raw data from a source without interpretation or transformation.
+
+### Normalize
+
+Maps raw data into OCI's canonical schema.
+
+### Resolve
+
+Handles duplicates, identity collisions, and uncertainty between entities.
+
+### Enrich
+
+Adds secondary metadata (genres, assets, keywords, etc.) additively.
+
+### Export
+
+Emits the indexed data in formats suitable for downstream systems.
+
+## Provenance and Confidence
+
+Every piece of data stored by OCI is associated with:
+
+- a source
+- a fetch timestamp
+- an optional confidence level
+
+Conflicting data is expected and preserved.
+"Unknown" and "uncertain" are valid outcomes.
+
+## Why This Exists
+
+Film culture is broader and stranger than most databases allow.
+
+Many existing systems:
+
+- flatten ambiguity
+- privilege a single source
+- erase minority or regional perspectives
+
+OCI exists to preserve the richness of cinema history without pretending it's tidy.
+
+## Project Status
+
+Open Cinema Index is under active development.
+
+The schema and CLI are expected to evolve.
+
+Contributions are welcome, especially those that respect the project's archival philosophy.
+
+## Environment Variables
+
+The project uses environment variables for secrets. Create a `.env` file based on `.env.example`
+
+```text
+WIKIDATA_USER_AGENT=open-cinema-index (your-email@example.com)
+TMDB_API_KEY=your_tmdb_api_key_here
+```
+
+- `WIKIDATA_USER_AGENT`: Required by Wikidata's API policy. It should identify your tool and provide a way to contact you.
+- `TMDB_API_KEY`: Required for fetching posters and other metadata from TMDb.
+