fix: Resolve CI failures and finalize linting

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      - name: Install Poetry
+        run: |
+          pip install poetry
+      - name: Install dependencies
+        run: |
+          poetry install
+      - name: Run ruff
+        run: |
+          poetry run ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      - name: Install Poetry
+        run: |
+          pip install poetry
+      - name: Install dependencies
+        run: |
+          poetry install
+      - name: Run tests
+        run: |
+          poetry run pytest

.gitignore

@@ -1,13 +1,122 @@
-# Python bytecode
+# Byte-compiled / optimized / DLL files
 __pycache__/
-*.pyc
+*.py[cod]
+*$py.class
 
-# PyTorch model files
-*.pt
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
 
-# Test artifacts
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
 .pytest_cache/
 test_projects/
 
-# Log files
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
 *.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyderworkspace
+
+# Rope project settings
+.ropeproject
+
+# PyCharm
+.idea/
+.project
+.pydevproject
+.settings/
+*.iml
+*.iws
+
+# VSCode
+.vscode/
+
+#mypy
+.mypy_cache/
+
+# PyTorch model files
+*.pt
+*.pth

README.md

@@ -4,11 +4,77 @@ Zebtrack Controller is a graphical application designed for object tracking in v
 
 ## Installation
 
-_Instructions on how to install the necessary dependencies and set up the environment will be added here._
+This project is managed with [Poetry](https://python-poetry.org/).
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/your-username/zebtrack-controller.git
+    cd zebtrack-controller
+    ```
+
+2.  **Install Poetry:**
+    Follow the official instructions at [python-poetry.org](https://python-poetry.org/docs/#installation) to install Poetry on your system.
+
+3.  **Install dependencies:**
+    Once Poetry is installed, run the following command in the project root to create a virtual environment and install the required dependencies:
+    ```bash
+    poetry install
+    ```
 
 ## Usage
 
-_Instructions on how to run the application and use its features will be added here._
+To run the application, use the following command from the project's root directory:
+
+```bash
+poetry run python -m zebtrack
+```
+
+This will launch the main graphical user interface.
+
+## Architecture
+
+The application is designed with a separation of concerns, loosely following a Model-View-Controller (MVC) pattern.
+
+```mermaid
+graph TD
+    subgraph "User Interface (View)"
+        GUI["GUI (Tkinter)"]
+    end
+
+    subgraph "Core Logic (Controller & Model)"
+        AppController
+        ProjectManager
+        Detector["Detector (Ultralytics/OpenVINO)"]
+        Settings
+    end
+
+    subgraph "I/O Subsystem"
+        FrameSource["FrameSource (Camera/Video)"]
+        Recorder
+        Arduino
+    end
+
+    GUI -- User Actions --> AppController
+    AppController -- Updates --> GUI
+
+    AppController -- Manages --> ProjectManager
+    AppController -- Uses --> Settings
+    AppController -- Controls --> Detector
+    AppController -- Controls --> Recorder
+    AppController -- Controls --> Arduino
+    AppController -- Gets Frames --> FrameSource
+
+    Detector -- Processes frames provided by --> AppController
+```
+
+*   **GUI**: The user interface, built with Tkinter.
+*   **AppController**: The central component that handles user input from the GUI and coordinates all other components.
+*   **ProjectManager**: Manages the creation, loading, and saving of project files and configurations.
+*   **Detector**: Performs object detection on video frames using models from `ultralytics` or `OpenVINO`.
+*   **FrameSource**: Provides video frames, either from a live camera feed or a video file.
+*   **Recorder**: Handles the saving of output video and tracking data.
+*   **Arduino**: Manages communication with an Arduino board for hardware I/O.
+*   **Settings**: Loads and manages application settings from configuration files.
 
 ## License
 

pyproject.toml

@@ -16,6 +16,7 @@ openvino = "==2025.1.0"
 ultralytics = ">=8.3.179,<9.0.0"
 pyyaml = "^6.0.2"
 pydantic = "^2.11.7"
+structlog = "^25.4.0"
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.12.9"

src/zebtrack/__main__.py

@@ -1,6 +1,8 @@
 import logging
 import tkinter as tk
 
+import structlog
+
 from zebtrack.core.controller import AppController
 from zebtrack.settings import settings
 from zebtrack.utils import set_seed
@@ -10,30 +12,53 @@ def main():
     """
     Initializes and runs the application.
     """
-    # Configure logging
+    # Configure logging with structlog
+    structlog.configure(
+        processors=[
+            structlog.stdlib.add_log_level,
+            structlog.stdlib.add_logger_name,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.UnicodeDecoder(),
+            structlog.processors.JSONRenderer()
+        ],
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+    # Route standard library logs to structlog
     logging.basicConfig(
         level=logging.INFO,
-        format="%(asctime)s - %(threadName)s - %(name)s - %(levelname)s - %(message)s",
-        filename="analysis.log",
-        filemode="w",  # Overwrite log file on each run
+        format="%(message)s",
+        handlers=[logging.FileHandler("analysis.log", mode="w")],
     )
 
+    log = structlog.get_logger()
+
     # Set seed for reproducibility before anything else
-    if settings and settings.reproducibility:
+    if settings and settings.reproducibility and settings.reproducibility.seed:
         set_seed(settings.reproducibility.seed)
+        log.info("reproducibility.seed.set", seed=settings.reproducibility.seed)
 
-    logging.info("Application starting.")
+    log.info("application.starting", component="main")
 
     try:
         root = tk.Tk()
         controller = AppController(root)
         controller.run()
-    except Exception as e:
-        logging.critical("An unhandled exception occurred.", exc_info=True)
+    except Exception:
+        log.critical("unhandled.exception", exc_info=True)
         # Optionally, show a message to the user
-        # messagebox.showerror("Fatal Error", f"A fatal error occurred: {e}\nSee analysis.log for details.")
+        # import tkinter.messagebox as messagebox
+        # messagebox.showerror(
+        #     "Fatal Error",
+        #     "A fatal error occurred. See analysis.log for details."
+        # )
     finally:
-        logging.info("Application finished.")
+        log.info("application.finished", component="main")
 
 
 if __name__ == "__main__":