From cd6c0bd80a990ae9384e19cf97005a864d496076 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 18 Jan 2026 09:22:48 +0000 Subject: [PATCH 1/4] Initial plan From bb7999cc18226cabccf671f0bb4f409f101cf625 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 18 Jan 2026 09:25:57 +0000 Subject: [PATCH 2/4] Add agents.md and update README.md to reference it Co-authored-by: Shuyib <12908522+Shuyib@users.noreply.github.com> --- README.md | 9 +++++++++ agents.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 agents.md diff --git a/README.md b/README.md index 1e69f6a..fa745b4 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ Learn more about tool calling - [Limitations](#limitations) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) +- [Agents Conventions](#agents-conventions) - [License](#license) @@ -1126,5 +1127,13 @@ When contributing, please ensure: - Sensitive content handling is verified - No real personal information is included in tests +## Agents Conventions + +We added an Agents Conventions document that harmonizes Makefile-derived developer conventions with augmentative best-practices inspired by Pragmatic AI Labs (Noah Gift) and the fast.ai developer style guide. + +Read the full conventions and recommended Makefile snippets in: [agents.md](./agents.md) + +This document is intentionally augmentive and non-breaking; it preserves existing Makefile behavior while recommending optional improvements for reproducibility, CI parity, and notebook hygiene. + ## License [License information](https://github.com/Shuyib/tool_calling_api/blob/main/LICENSE). diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..9dbb6f5 --- /dev/null +++ b/agents.md @@ -0,0 +1,60 @@ +# Agents Conventions + +This document harmonizes Makefile-derived developer conventions with augmentative best-practices inspired by Noah Gift / Pragmatic AI Labs and the fast.ai developer style guide. It is written to be non-breaking and augmentive: preserve existing Makefile behavior while recommending optional improvements for reproducibility, discoverability, CI parity, and notebook hygiene. + +## Purpose +Provide a concise, actionable reference for: +- How agents (developers, automation) should run tasks via Makefile. +- How to keep local development and CI behavior consistent. +- Notebook and coding style guidance informed by Pragmatic AI Labs (Noah Gift) and fast.ai. + +## Quick summary of existing Makefile behavior (source: repo Makefile) +- Virtual env: `.venv`, activate script at `.venv/bin/activate` +- Key variables: `PYTHON=.venv/bin/python3`, `PIP=.venv/bin/pip3`, `DOCKER_IMAGE_NAME`, `DOCKER_IMAGE_VERSION`, `DOCKER_IMAGE_TAG` +- Standard targets present: `venv/bin/activate`, `activate`, `install`, `docstring`, `format`, `clean`, `lint`, `test` +- `.ONESHELL:` and `.DEFAULT_GOAL := all` are used. + +## Core agent recommendations (non-breaking, augmentive) +1. Use venv binaries directly inside Make targets and CI: + - Prefer `.venv/bin/python` and `.venv/bin/pip` in recipes to avoid relying on shell activation persistence. +2. Keep targets idempotent and declarative: + - Make sure `install`, `format`, `lint`, and `test` can be re-run safely. +3. Add discoverability and CI-parity targets (suggested, optional): + - `.PHONY: help ci install-dev` and a `help` target that lists commands. + - `ci` target runs same steps as CI (e.g., `install-dev format lint test`). +4. Separate runtime and dev dependencies: + - Introduce `requirements-dev.txt` and `install-dev` target to install linting/test tools. +5. Makefile UX improvements inspired by Pragmatic AI Labs: + - Add helpful echo messages, fail-fast settings (e.g., `set -euo pipefail` in multi-line recipes), and explicit `.PHONY`. +6. Docker ergonomics: + - Use `DOCKER_IMAGE_TAG` for build/push targets and consider deriving version from git tags in CI. +7. Notebook and experiment hygiene (fast.ai-aligned): + - Keep notebooks runnable top-to-bottom; move production logic into `.py` modules. + - Strip outputs before commit (use `nbstripout`, `jupytext`, or pre-commit hooks). + - Store experiment artifacts under `runs/` or `artifacts/`. + +## Suggested non-breaking Makefile snippets (optional additions) +- help, venv, install-dev, ci, docker-build examples using `.venv/bin/*` binaries and `.PHONY` list (see repository README or conventions for full snippet). + +## Linting, formatting, docstrings, testing +- Format: keep `black *.py utils/*.py tests/*.py` but run via `.venv/bin/black` in CI or `install-dev`. +- Docstrings: `pyment -w -o numpydoc *.py` remains valid—document usage in CONTRIBUTING. +- Lint: keep `pylint --disable=R,C --errors-only *.py` for errors-only mode; consider `lint-full` for stricter checks. +- Test: use `pytest` invocation from Makefile but ensure small, deterministic tests for CI. + +## Reproducibility & releases +- Consider `pip-compile`/lockfiles or poetry for reproducible builds when releasing. +- Add `bump-version` or derive Docker tag from git in CI for consistent releases. + +## Notebook- and fast.ai-specific guidance +- Prefer short, testable functions; avoid heavy computations committed to notebooks. +- Convert critical notebook logic to modules and add unit tests. +- Use `pre-commit` with nbstripout/jupytext and black/isort to keep diffs clean. + +## Documentation & contribution +- Keep this file updated when adding Makefile targets or changing developer workflow. +- Add `CONTRIBUTING.md` pointing to `make help`, `make ci`, and notebook guidelines. + +## References and sources +- fast.ai developer style guide: https://docs.fast.ai/dev/style.html +- Pragmatic AI Labs / Noah Gift: https://paiml.com/ and https://noahgift.com/ From f9442442970eaf5040b54a5c20a7373a56a0ce4a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 18 Jan 2026 09:30:34 +0000 Subject: [PATCH 3/4] Add credit to agents.md convention source Co-authored-by: Shuyib <12908522+Shuyib@users.noreply.github.com> --- agents.md | 1 + 1 file changed, 1 insertion(+) diff --git a/agents.md b/agents.md index 9dbb6f5..12dd42f 100644 --- a/agents.md +++ b/agents.md @@ -58,3 +58,4 @@ Provide a concise, actionable reference for: ## References and sources - fast.ai developer style guide: https://docs.fast.ai/dev/style.html - Pragmatic AI Labs / Noah Gift: https://paiml.com/ and https://noahgift.com/ +- agents.md convention: https://github.com/agentsmd/agents.md From 3d55327cb71e09f586e7ffc2b725e975a782cadd Mon Sep 17 00:00:00 2001 From: Legendrea Date: Sun, 18 Jan 2026 09:45:11 +0000 Subject: [PATCH 4/4] Update agents.md to clarify sources and improve wording Removed reference to Noah Gift and added clarification about the source of best practices. --- agents.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/agents.md b/agents.md index 12dd42f..26ff56f 100644 --- a/agents.md +++ b/agents.md @@ -1,12 +1,12 @@ # Agents Conventions -This document harmonizes Makefile-derived developer conventions with augmentative best-practices inspired by Noah Gift / Pragmatic AI Labs and the fast.ai developer style guide. It is written to be non-breaking and augmentive: preserve existing Makefile behavior while recommending optional improvements for reproducibility, discoverability, CI parity, and notebook hygiene. +This document harmonizes Makefile-derived developer conventions with augmentative best-practices inspired by Pragmatic AI Labs and the fast.ai developer style guide. It is written to be non-breaking and augmentive: preserve existing Makefile behavior while recommending optional improvements for reproducibility, discoverability, CI parity, and notebook hygiene. ## Purpose Provide a concise, actionable reference for: - How agents (developers, automation) should run tasks via Makefile. - How to keep local development and CI behavior consistent. -- Notebook and coding style guidance informed by Pragmatic AI Labs (Noah Gift) and fast.ai. +- Notebook and coding style guidance informed by Pragmatic AI Labs on YT and fast.ai. ## Quick summary of existing Makefile behavior (source: repo Makefile) - Virtual env: `.venv`, activate script at `.venv/bin/activate`