Restructure project and use 'uv'

.gitignore

@@ -0,0 +1,151 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# 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
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# IDE
+.idea
+
+# Cython debug symbols
+cython_debug/
+
+# Custom ignore files/folders
+.DS_Store
+.pypirc
+.vscode
+*credentials*.json
+scratch*

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff-check
+        entry: ruff check --fix --force-exclude app etc
+        language: system
+        always_run: true
+        pass_filenames: false
+      - id: ruff-format
+        name: ruff-format
+        entry: ruff format --force-exclude app etc
+        language: system
+        always_run: true
+        pass_filenames: false
+      - id: branch-name-and-commit-permission-check
+        name: branch name and commit permission check
+        entry: bash ./etc/branch-name-check.sh
+        language: system
+        always_run: true
+        pass_filenames: false

.python-version

@@ -0,0 +1 @@
+3.13

LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Saurabh Ghanekar
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

compose.yaml

@@ -0,0 +1,28 @@
+services:
+  arcana-in-action:
+    build:
+      context: .
+      target: runtime
+    ports:
+      - 8698:7860
+    networks:
+      - arcana-in-action-net
+      - arcana-gateway-net
+    volumes:
+      - ./app:/app
+    environment:
+      ARCANA_API_KEY: "${ARCANA_API_KEY}"
+      MONGO_URI: "${MONGO_URI}"
+      OPENBLAS_NUM_THREADS: "${OPENBLAS_NUM_THREADS:-4}"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://arcana-in-action/health"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+
+networks:
+  arcana-in-action-net:
+    name: arcana-in-action-network
+  arcana-gateway-net:
+    name: arcana-gateway-network
+    external: true

etc/branch-name-check.sh

@@ -0,0 +1,9 @@
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+if [[ $BRANCH =~ (master|main|develop) ]]; then
+    echo "You are on branch $BRANCH. Are you sure you want to commit to this branch?"
+    echo "If so, commit with -n to bypass this pre-commit hook."
+    exit 1
+fi
+
+exit 0

etc/key_generator.py

@@ -0,0 +1,12 @@
+import secrets
+import string
+
+
+def generate_key(length=64):
+    alphabet = string.ascii_letters + string.digits
+    key = "".join(secrets.choice(alphabet) for _ in range(length))
+    return key
+
+
+key = generate_key()
+print(key)

etc/versioning.py

@@ -0,0 +1,244 @@
+import re
+import tomllib
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.traceback import install
+
+install(extra_lines=0, max_frames=10)
+
+
+class VersionLevel(StrEnum):
+    MAJOR = "major"
+    MINOR = "minor"
+    PATCH = "patch"
+    ALPHA = "alpha"
+    BETA = "beta"
+    RC = "rc"
+    DEV = "dev"
+    RELEASE = "release"
+
+
+class SupportedBackend(StrEnum):
+    POETRY = "poetry"
+    UV = "uv"
+
+
+def load_config():
+    pyproject_path = Path.cwd() / "pyproject.toml"
+    if pyproject_path.exists():
+        with open(pyproject_path, "rb") as f:
+            pyproject_data = tomllib.load(f)
+            config = pyproject_data.get("tool", {}).get("versioning", {}).get("files")
+
+            backend = (
+                pyproject_data.get("tool", {}).get("versioning", {}).get("backend")
+            )
+            if backend is None:
+                raise RuntimeError(
+                    "`pyproject.toml` file doesn't contain `tool.versioning.backend` property."
+                )
+            match SupportedBackend(backend):
+                case SupportedBackend.POETRY:
+                    version = (
+                        pyproject_data.get("tool", {}).get("poetry", {}).get("version")
+                    )
+                case SupportedBackend.UV:
+                    version = pyproject_data.get("project", {}).get("version")
+
+            if version is None:
+                raise RuntimeError(
+                    "`pyproject.toml` file doesn't contain `version` property."
+                )
+
+            return version, config
+    else:
+        raise RuntimeError("Unable to locate `pyproject.toml` file.")
+
+
+def parse_version(version) -> dict[str, str | Any]:
+    VERSION_PATTERN = re.compile(
+        r"^"
+        r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
+        r"(?:(?P<pre_type>a|b|rc)(?P<pre_num>\d+))?"
+        r"(?:\.post(?P<post>\d+))?"
+        r"(?:\.dev(?P<dev>\d+))?"
+        r"$"
+    )
+
+    pattern_match = VERSION_PATTERN.match(version)
+    if pattern_match:
+        return pattern_match.groupdict()
+    else:
+        raise ValueError(
+            f"Invalid version format {version}. Expected format: MAJOR.MINOR.PATCH[preTYPE[preNUM][.dev]]"
+        )
+
+
+def find_substring_index(strings: list[str], substring: str) -> int:
+    return next(i for i, string in enumerate(strings) if substring in string)
+
+
+def find_variable_and_replace_value_in_file(
+    file_name: str,
+    variable_name: str,
+    new_value: str,
+    dry_run: bool,
+    return_changed_line_number: bool = False,
+) -> None | int:
+    file = Path.cwd() / file_name
+    text = file.read_text().splitlines(keepends=True)
+    line_index = find_substring_index(text, variable_name)
+    text[line_index] = text[line_index].replace(
+        re.search(f"{variable_name}.*$", text[line_index]).group(0),
+        variable_name + " = " + f'"{new_value}"',
+    )
+
+    if not dry_run:
+        file.write_text("".join(text))
+
+    if return_changed_line_number:
+        return line_index + 1
+
+
+def sync_version_in_different_files(
+    version, config, dry_run: bool
+) -> list[dict[str, int | str]]:
+    files_synced = []
+    if "version_variable" in config:
+        for value in config.get("version_variable"):
+            file_name = value.split(":")[0]
+            variable_name = value.split(":")[1]
+
+            line_number = find_variable_and_replace_value_in_file(
+                file_name,
+                variable_name,
+                version,
+                dry_run,
+                return_changed_line_number=True,
+            )
+
+            files_synced.append(
+                {
+                    "file_path": file_name,
+                    "line_number": line_number,
+                }
+            )
+
+    return files_synced
+
+
+def versioning(level: VersionLevel, current_version: str, dry_run: bool) -> str:
+    version_parts = parse_version(current_version)
+
+    match level:
+        case VersionLevel.MAJOR:
+            new_version = f"{int(version_parts['major']) + 1}.0.0"
+        case VersionLevel.MINOR:
+            new_version = (
+                f"{version_parts['major']}.{int(version_parts['minor']) + 1}.0"
+            )
+        case VersionLevel.PATCH:
+            new_version = f"{version_parts['major']}.{version_parts['minor']}.{int(version_parts['patch']) + 1}"
+        case VersionLevel.ALPHA | VersionLevel.BETA | VersionLevel.RC:
+            pre_type_map = {
+                VersionLevel.ALPHA: "a",
+                VersionLevel.BETA: "b",
+                VersionLevel.RC: "rc",
+            }
+
+            if version_parts["pre_type"] == pre_type_map[level]:
+                pre_num = int(version_parts["pre_num"] or 0) + 1
+            else:
+                pre_num = 1
+
+            new_version = f"{version_parts['major']}.{version_parts['minor']}.{version_parts['patch']}{pre_type_map[level]}{pre_num}"
+        case VersionLevel.DEV:
+            if version_parts["pre_type"] and version_parts["pre_num"]:
+                pre_parts = f"{version_parts['pre_type']}{version_parts['pre_num']}"
+            else:
+                pre_parts = ""
+
+            dev_num = int(version_parts["dev"] or 0) + 1
+            new_version = f"{version_parts['major']}.{version_parts['minor']}.{version_parts['patch']}{pre_parts}.dev{dev_num}"
+        case VersionLevel.RELEASE:
+            if (
+                version_parts["pre_type"]
+                or version_parts["pre_num"]
+                or version_parts["dev"]
+            ):
+                new_version = f"{version_parts['major']}.{version_parts['minor']}.{version_parts['patch']}"
+            else:
+                raise ValueError(
+                    f"The project is already on release version {current_version}"
+                )
+
+    if not dry_run:
+        find_variable_and_replace_value_in_file(
+            "pyproject.toml", "version", new_version, dry_run=False
+        )
+
+    return new_version
+
+
+def display_update_summary(
+    console: Console, files_synced: list[dict[str, int | str]]
+) -> None:
+    grid = Table.grid()
+    grid.add_column(justify="center")
+
+    for sync_infomation in files_synced:
+        grid.add_row(
+            f"Synced version updates in file [cyan]`{sync_infomation['file_path']}`[/cyan] at line [cyan]{sync_infomation['line_number']}[/cyan]"
+        )
+
+    console.print(
+        Panel(grid, title="Version Update Summary", border_style="blue", padding=(1, 2))
+    )
+
+
+@click.command()
+@click.argument(
+    "level", type=click.Choice([vl.value for vl in VersionLevel], case_sensitive=False)
+)
+@click.option(
+    "--show-summary",
+    "-s",
+    is_flag=True,
+    help="Show what files changed",
+)
+@click.option(
+    "--dry-run",
+    "-d",
+    is_flag=True,
+    help="Show what would be done without making changes",
+)
+def main(level: str, show_summary: bool, dry_run: bool):
+    console = Console()
+
+    current_version, versioning_config = load_config()
+    new_version = versioning(VersionLevel(level), current_version, dry_run)
+    files_synced = sync_version_in_different_files(
+        new_version, versioning_config, dry_run
+    )
+
+    if dry_run:
+        console.print(
+            f"[yellow]Dry Run[/yellow]: Bumped version: [bold cyan]{current_version}[/bold cyan] :arrow_right: [bold green]{new_version}[/bold green]"
+        )
+    else:
+        console.print(
+            f"Bumped version: [bold cyan]{current_version}[/bold cyan] :arrow_right: [bold green]{new_version}[/bold green]"
+        )
+
+    if show_summary:
+        display_update_summary(console, files_synced)
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "arcana-in-action"
+version = "0.0.0"
+description = "Huggingface Demo showcasing how Arcana works"
+authors = [{ name = "Saurabh Ghanekar", email = "[email protected]" }]
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi-slim>=0.115",
+    "uvicorn>=0.34",
+    "pydantic>=2.10",
+    "pillow>=11.1",
+    "arcana-codex>=0.2",
+    "llama-cpp-python>=0.3",
+    "huggingface-hub>=0.29",
+    "pymongo>=4.11",
+    "email-validator>=2.2",
+]
+
+
+[dependency-groups]
+dev = ["click>=8.1", "pre-commit>=4.0", "rich>=13.9", "ruff>=0.9"]
+test = ["pytest>=8.3", "pytest-cov>=6.0"]
+
+
+[tool.uv]
+default-groups = ["dev", "test"]
+
+
+[tool.ruff]
+line-length = 88
+
+
+[tool.ruff.lint]
+select = [
+    # "D",      # pydocstyle
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG001", # unused arguments in functions
+]
+ignore = [
+    "E501", # line too long, handled by black
+    "B008", # do not perform function calls in argument defaults
+    "W191", # indentation contains tabs
+    "B904", # Allow raising exceptions without from e, for HTTPException
+]
+
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.versioning]
+backend = "uv"
+
+[tool.versioning.files]
+version_variable = ["app/app/main.py:__version__"]

requirements.txt

@@ -1,7 +0,0 @@
-fastapi-slim
-uvicorn[standard]
-arcana-codex
-pydantic
-pillow
-llama-cpp-python
-huggingface-hub