The one test
A runnable repo passes the fresh clone test. Someone should be able to clone it, install dependencies, run one command, and see output.
Do not assume they have your folder structure, API key file, or college laptop setup.
What runnable means
Your script already reads data and calls an API or mock API. Now make it usable by another builder, mentor, or recruiter.
They should not need to message you on WhatsApp for missing files or commands.
Minimum repo shape
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done
Simple file layout
Keep the first version boring. Boring is easy to run during judging.
ai-summary-tool/
main.py
requirements.txt
README.md
sample_input.json
output/
.gitkeepRequirements file
requirements.txt is just a list of pip packages. Do not include Python standard library modules like json, os, csv, or pathlib.
If you used requests to call an API, include it.
requests==2.32.3
python-dotenv==1.0.1Avoid local paths
A common bug is hardcoding paths like C:\Users\Aman\Desktop\data.json or /home/you/project/input.json. That only works on your laptop.
Use paths relative to the script or accept a file path as a command-line argument.
Accept input path
This pattern lets anyone run your tool with their own file. It also works well with your sample file.
import argparse
import json
from pathlib import Path
parser = argparse.ArgumentParser(description="Process input data and write output")
parser.add_argument("--input", default="sample_input.json", help="Path to input JSON")
parser.add_argument("--output", default="output/result.json", help="Path to output JSON")
args = parser.parse_args()
input_path = Path(args.input)
output_path = Path(args.output)
output_path.parent.mkdir(parents=True, exist_ok=True)
with input_path.open("r", encoding="utf-8") as f:
data = json.load(f)
result = {
"items_read": len(data) if isinstance(data, list) else 1,
"status": "processed"
}
with output_path.open("w", encoding="utf-8") as f:
json.dump(result, f, indent=2)
print(f"Wrote {output_path}")Handle secrets safely
If your real API needs a key, do not commit the key. Read it from an environment variable or a .env file, and commit a .env.example instead.
For hackathon review, include a mock mode if possible. That lets judges run your repo without your paid or private key.
# .env.example
API_KEY=put_your_key_here
# Run with a mock mode if your script supports it
python main.py --input sample_input.json --output output/result.json --mockDo this now
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done