Add agents.md convention document and reference from README

README.md

@@ -39,6 +39,7 @@ Learn more about tool calling <https://gorilla.cs.berkeley.edu/leaderboard.html>
 - [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).

agents.md

@@ -0,0 +1,61 @@
+# Agents Conventions
+
+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 on YT 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/
+- agents.md convention: https://github.com/agentsmd/agents.md