{"id":15902513,"url":"https://github.com/nikolasent/ai-project-template","last_synced_at":"2025-03-20T19:31:23.792Z","repository":{"id":239521556,"uuid":"799697879","full_name":"NikolasEnt/AI-project-template","owner":"NikolasEnt","description":"General-purpose structure template for DS/ML/CV/DL/AI projects and Development Style Guide","archived":false,"fork":false,"pushed_at":"2024-09-29T01:33:30.000Z","size":20,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-07T11:41:21.210Z","etag":null,"topics":["ai","deep-learning","machine-learning","ml-template","python","styleguide"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NikolasEnt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-12T22:33:32.000Z","updated_at":"2024-09-29T01:33:33.000Z","dependencies_parsed_at":"2024-10-26T07:35:24.131Z","dependency_job_id":"c4043fe8-1735-40cd-84d9-8abdab773fdd","html_url":"https://github.com/NikolasEnt/AI-project-template","commit_stats":null,"previous_names":["nikolasent/ai-project-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikolasEnt%2FAI-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikolasEnt%2FAI-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikolasEnt%2FAI-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikolasEnt%2FAI-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NikolasEnt","download_url":"https://codeload.github.com/NikolasEnt/AI-project-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221799169,"owners_count":16882380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","deep-learning","machine-learning","ml-template","python","styleguide"],"created_at":"2024-10-06T11:41:22.930Z","updated_at":"2025-03-20T19:31:23.780Z","avatar_url":"https://github.com/NikolasEnt.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python base project template\n\nThis is a basic Python project that can be used as a starting point for any\nData Science or AI projects.\n\nThe template includes:\n\n- Project structure, defined by the repo\n- Docker-based development environment, described below\n- Development [Style Guide](GUIDE.md)\n\n## Project structure\n\n### Directories\n\n* `data`: Data, including datasets for training and saved models. In most cases, the content of this directory should not be tracked by Git, except for small metadata files, like `.dvc` files, produced by [DVC](https://dvc.org/doc).\n* `src`: The project source code.\n* `scripts`: Small standalone scripts and utils. This directory can also contain entry point scripts, such as code to start training a model.\n* `configs`: Configuration files: YAML, JSON, TOML, and etc.\n* `tests`: Various test files, such as unit tests for `pytest`.\n* `docs`: Detailed documentation of the project, for example, as a collection of `.md` files with relevant images.\n* `notebooks`: Jupyter notebooks for data exploration and visualisation.\n\n### Files\n\n* `README.md`: The main readme file for the project, providing a high-level overview of its purpose, functionality and how to get started.\n* `Makefile`: A makefile for automating environment build and run processes. It may contain additional targets, like running tests, or generating documentation.\n* `Dockerfile`: Defines the project environment.\n* `requirements.txt`: A text file listing required Python packages with versions.\n* `.dockerignore`: A file specifying files and directories to exclude when building a Docker image.\n* `pyproject.toml`: The project configuration file defines metadata and other project-specific configurations.\n* `.gitignore`: A file listing files and directories that Git should not track.\n* `.pre-commit-config.yaml`: Configuration file for the pre-commit.\n\n## Environment setup\n\nThe project uses [Docker](https://docs.docker.com/) to provide a reproducible environment for running\nthe code. The environment is controlled by [Makefile](Makefile), which can be customized\nfor the project needs.\n\nThe provided Docker environment is a basic Python 3.11 image, but it can be\nconfigured by editing [Dockerfile](Dockerfile) to include any additional Linux\npackages required for the project. Alternatively, one can use different base\nDocker images, for example [nvidia/cuda](https://hub.docker.com/r/nvidia/cuda/#!).\nConfigure [requirements.txt](requirements.txt) to include any additional Python\npackages.\n\nTo build the environment, run in the project home directory:\n```bash\nmake build\n```\n\nOnce the image is built, start the container with:\n```bash\nmake run\n```\n\nThe container has the project root directory mounted to `/workdir`,\nso all the local files can be accessed in the directory from within the container. Files saved\ninside `/workdir` will be saved in the project root directory of the host machine.\n\nIt is a good practice to develop inside the container using one's favorite IDE\n(e.g., VS Code or PyCharm) and execute the code from within the container.\n\nNote: the template is meant to be used as a development environment and for\nrunning the code in experimental setups. Production scenarios may require further modifications\nto suit one's needs, including security features.\n\n### Environment variables\n\nIn order to provide environment variables, such as secrets, it is a common practice to define them in the `.env` file and add the file to the Docker run command in the Makefile with `--env-file=.env`. A sample structure of the `.env` file can be provided in the `.env.sample` file to make it easier for the user to fill with required values.\n\n### X11 support\n\nIn order to run the code in a container with X11 support, for example, to enable interactive visualisation, the Docker run command in the Makefile should include the following lines:\n\n```\n        -v /tmp/.X11-unix:/tmp/.X11-unix \\\n        -v $(HOME)/.Xauthority:/root/.Xauthority:rw \\\n        -e DISPLAY=$(DISPLAY)\n```\n\nThis allows use of the Linux host X11 server to access the display. Note that other host types may require a different approach.\n\n## Pre-commit hooks\n\nThe project provides some basic pre-commit hooks, helping with code linting before committing. This is just an aid, although it's important to ensure that the final code is formatted correctly, follows PEP8, and adheres to the development [Style Guide](GUIDE.md).\n\nTo install pre-commit hooks, run in the project home directory:\n```bash\npip install pre-commit\npre-commit install\npre-commit install-hooks\n```\n\nThe pre-commit hooks are defined in [.pre-commit-config.yaml](.pre-commit-config.yaml) and configured in [pyproject.toml](pyproject.toml). Feel free to customize them as needed.\n\nThe default provided hooks include isort for sorting imports and Ruff for linting. If preferred, other hooks can be installed. If desired, [Ruff Formatter](https://docs.astral.sh/ruff/formatter/) can be enabled by uncommenting the corresponding block in the `.pre-commit-config.yaml` file.\n\nThe installed pre-commits can be updated with:\n\n```bash\npre-commit autoupdate\n```\n\nThe command will update `.pre-commit-config.yaml` file, so it needs to be commited to git.\n\n## Links\n\nThe template is the result of years of experience within various development and research teams, as well as the result of inspiration from multiple successful ML competition projects, such as:\n* [1st place solution for SoccerNet Camera Calibration Challenge at CVPR 2023](https://github.com/NikolasEnt/soccernet-calibration-sportlight)\n* [1st place solution for SoccerNet Ball Action Spotting Challenge at CVPR 2023](https://github.com/lRomul/ball-action-spotting)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolasent%2Fai-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikolasent%2Fai-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolasent%2Fai-project-template/lists"}