Apply for AI Grants India

Why GitHub matters for machine learning

GitHub is more than a place to store notebooks. Used well, it becomes the operating system for an ML project: it records decisions, makes experiments inspectable, supports collaboration, and gives reviewers evidence that your model works beyond one laptop. For Indian students, researchers, and early-stage founders, a well-structured repository can also become a stronger portfolio than a screenshot of model accuracy.

The goal is not to upload every file you create. The goal is to make another person able to understand the problem, reproduce a baseline, evaluate the result, and extend the work safely. If you are starting with a portfolio project, compare your idea with machine learning portfolio projects for beginners in India and choose a problem with accessible data and a measurable outcome.

1. Define the project before creating the repository

Write a short project brief before opening GitHub. It should answer:

• Problem: What decision or prediction are you improving?
• Users: Who will use the output, and in what setting?
• Input and target: What data enters the system, and what exactly is predicted?
• Metric: Which primary metric matters, and why?
• Constraints: What are the latency, cost, language, privacy, or hardware limits?
• Success threshold: What result is useful enough to justify further work?

Avoid vague goals such as “build an AI model.” A stronger scope is “classify Marathi support messages into five routing categories with macro-F1 above 0.80.” For Indic-language work, document script, dialect, transliteration, annotation quality, and code-mixing early. The low-resource Indic natural language processing guide is a useful reference when language coverage is part of the project.

Create the repository with a clear name, a one-line description, and the correct visibility. Use a private repository for confidential data, proprietary code, or an unreleased product. Remember that making a repository private later does not erase copies, forks, cached artifacts, or secrets that were previously exposed.

2. Use a structure that separates code, data, and results

A practical starting layout is:

project-name/
├── README.md
├── LICENSE
├── pyproject.toml
├── .gitignore
├── .env.example
├── configs/
├── data/
│   ├── raw/
│   ├── interim/
│   └── processed/
├── notebooks/
├── src/project_name/
├── tests/
├── scripts/
├── reports/
│   └── figures/
└── .github/
    └── workflows/

Keep reusable logic in src/, not buried in notebook cells. Use notebooks for exploration, visualisation, and short demonstrations. Store dataset instructions and download scripts rather than committing large or restricted datasets. Add data, model checkpoints, logs, and local environments to .gitignore.

A minimal setup might include:

git init
git add .
git commit -m "Create reproducible project scaffold"
git branch -M main
git remote add origin https://github.com/ORG/REPO.git
git push -u origin main

Pin dependencies with pyproject.toml or a locked requirements file. Record the Python version, operating-system assumptions, CUDA version where relevant, and whether the project was tested on CPU. A reviewer should not have to guess which package versions produced your results.

3. Make data and experiments reproducible

A model score without provenance is difficult to trust. Record:

• Dataset source, licence, access date, and version or hash
• Collection and labelling method
• Train, validation, and test split logic
• Preprocessing and feature transformations
• Random seeds and hardware used
• Model configuration and training command
• Evaluation results, including baselines and failure cases

Never commit API keys, passwords, private records, or personal data. Use environment variables locally, commit only .env.example, and rotate a credential immediately if it reaches Git history. For large files, consider Git LFS or external object storage, but document the download process and checksums.

Create one command that a new contributor can run, such as make train, python scripts/evaluate.py, or a documented Python module invocation. Save configuration separately from code so experiments can be compared. A simple results table is often enough:

| Experiment | Features | Model | Macro-F1 | Notes |
|---|---|---|---:|---|
| baseline | TF-IDF | logistic regression | 0.71 | CPU |
| exp-02 | TF-IDF + class weights | linear SVM | 0.76 | improved minority classes |

Include qualitative errors, not just the best number. For an Indian-language classifier, show examples across scripts and code-mixed inputs while removing sensitive information.

4. Treat notebooks as presentation, not production

Notebooks are useful for exploration but become fragile when cells must be executed in an undocumented order. Keep notebooks short, restart the kernel, run all cells from top to bottom, and remove accidental outputs or secrets. Move data loading, preprocessing, training, and evaluation into tested modules under src/.

A clean workflow is:

1. Download or locate data using a documented script.
2. Validate schema and split data without leakage.
3. Train a baseline through a repeatable command.
4. Run evaluation on the untouched test set.
5. Generate figures and a report from saved predictions.
6. Link the result to a commit, configuration, and dataset version.

For larger applications—such as an agent or voice interface—separate model code from APIs, queues, storage, and monitoring. The architecture lessons in building distributed systems with AI agents can help when your repository grows beyond a single training script.

5. Add quality checks with GitHub workflows

A small continuous-integration workflow catches avoidable errors before they reach the main branch. Run tests, formatting, linting, import checks, and a lightweight data or pipeline validation job on every pull request. Do not run expensive GPU training on every commit; use a small fixture dataset for CI and schedule larger evaluations separately.

Useful checks include:

• Unit tests for preprocessing and metric calculations
• A test that verifies no target leakage enters features
• Schema validation for incoming data
• Formatting with Black or Ruff-compatible tooling
• Dependency and secret scanning
• A smoke test that loads the model and makes one prediction

Protect the main branch, require pull-request reviews, and use issue templates for bugs, experiments, and feature requests. Keep commits focused and write messages that explain intent. When reviewing a pull request, ask whether the metric change is statistically meaningful, whether data leakage is possible, and whether the README still matches the code.

If your project is intended for public contribution, review how to contribute to AI GitHub repositories in India for practical guidance on issues, pull requests, licences, and responsible collaboration.

6. Write documentation that earns trust

Your README should let a new user reach a meaningful result quickly. Include:

• What the project does and who it is for
• A short demo, sample output, or screenshot
• Installation and tested environment
• Dataset access and licence
• Training and evaluation commands
• Baseline and current results
• Known limitations, bias, and unsafe use cases
• Contribution instructions and licence
• Citation or contact details, if applicable

Add a MODEL_CARD.md or equivalent for intended use, training data, evaluation slices, limitations, and ethical considerations. If the project handles health, finance, education, or legal information, do not present an experimental score as production readiness. Define how human review, consent, retention, and access control work.

7. Release a usable version

Use Git tags and GitHub Releases for stable milestones. A release should state what changed, how to reproduce the result, compatibility requirements, and whether model weights or datasets are included. Record the commit, configuration, and dependency lockfile used for the release.

For a portfolio project, pin a demo to a small, safe example rather than promising an unsupported production service. For a product, document inference cost, latency, monitoring, rollback, and model-update procedures. If you are building an open-source AI project, study the repository conventions in the Indian open-source AI developer projects guide.

A practical launch checklist

Before sharing your repository, verify that:

• A fresh environment can install dependencies successfully.
• The README explains the problem, data, commands, and limitations.
• No secrets, private data, or oversized accidental files are tracked.
• A baseline and an honest evaluation are included.
• Tests and CI pass on a clean checkout.
• Dataset and model licences permit your intended use.
• Results can be traced to a commit and configuration.
• Issues and contribution rules are clear.

A strong GitHub ML project is not defined by its folder count or the size of its model. It is defined by whether someone else can inspect the assumptions, reproduce the evidence, understand the limitations, and contribute without breaking the workflow.