Skip to content

Add AGENTS.md #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 21, 2025
Merged

Add AGENTS.md #47

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b911dc9
Add AGENTS.md
akegaviar Aug 21, 2025
3777bad
docs(agents): clarify dev prefix for metrics
smypmsa Aug 21, 2025
bc61396
docs(agents): remove mentioning unit tests
smypmsa Aug 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# AGENTS Guidelines for This Repository

This repository contains a Python-based Vercel Functions application for monitoring RPC node response times. When working on the project interactively with an agent (e.g. the Codex CLI) please follow the guidelines below to ensure smooth development and testing.

## 1. Use Test Scripts for Local Development

* **Always use the test scripts** (`test_api_read.py`, `test_api_write.py`, `test_update_state.py`) for local testing and development.
* **Do _not_ deploy to Vercel during the agent session** unless explicitly requested. Deployments should be handled outside of the interactive workflow to avoid disrupting production services.
* **Create a `.env.local` file** with the necessary environment variables before testing locally.

## 2. Keep Dependencies in Sync

If you add or update dependencies:

1. Update `requirements.txt` with the new package and version.
2. Reinstall dependencies in your virtual environment with `pip install -r requirements.txt`.
3. Verify compatibility with Python 3.9+ as specified in the project.

## 3. Coding Conventions

* Follow PEP 8 style guidelines.
* Use type hints for all function parameters and return values.
* Include Google-style docstrings for all functions and classes.
* Keep cyclomatic complexity below 10 (enforced by Ruff).
* Prefer composition over inheritance when designing metric classes.

## 4. Code Quality Checks

Before completing any task, run these quality checks:

| Command | Purpose |
| --------------------- | ------------------------------------------------- |
| `black .` | Format code to project standards |
| `ruff check .` | Run linting checks |
| `ruff check . --fix` | Auto-fix linting issues where possible |
| `mypy .` | Run type checking |

## 5. Testing Guidelines

* Test new metrics locally using the appropriate test script:
- `python tests/test_api_read.py` for read metrics
- `python tests/test_api_write.py` for write metrics
- `python tests/test_update_state.py` for state updates
* Ensure `endpoints.json` is properly configured before testing.
* Mock external API calls when writing unit tests.
Comment on lines +44 to +45
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Clarify where endpoints.json lives and/or provide a template

If contributors don’t know the expected path or schema, tests can fail unexpectedly. Please either document the canonical path (e.g., repo root vs tests/) and a minimal schema or include a sample file.

Run this to locate references and decide where to point the docs:

🏁 Script executed:

#!/bin/bash
# Find endpoints.json references and nearby context to confirm location/schema.
rg -n -C2 -i 'endpoints\.json' || true

# Also look for any example/template files in the repo.
fd -a 'endpoints*.json' -E '**/node_modules/**' -E '**/.venv/**'

Length of output: 1633

Clarify endpoints.json location and template in AGENTS.md

Please update AGENTS.md (around line 44) to explicitly state where endpoints.json should live and how to initialize it. For example:

  • Note that tests load the file from the repository root (Path(project_root) / "endpoints.json").
  • Remind contributors to copy the provided template: 
    cp endpoints.json.example endpoints.json
  • Optionally, link to the full schema in README.md under “RPC Provider Configuration.”

Suggested replacement for line 44:

- * Ensure `endpoints.json` is properly configured before testing.
+ * Ensure `endpoints.json` (located at the project root) is configured—copy from `endpoints.json.example` and update your values (see README.md for full schema).

This will prevent unexpected test failures due to a missing or mislocated configuration file.

🧰 Tools
🪛 LanguageTool

[grammar] ~44-~44: There might be a mistake here.
Context: ...` is properly configured before testing. * Mock external API calls when writing uni...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In AGENTS.md around lines 44-45, clarify where endpoints.json must live and how
to create it: state tests load Path(project_root)/"endpoints.json", instruct
contributors to initialize it from the template (e.g., copy
endpoints.json.example to endpoints.json), and add a note/link to the RPC
Provider Configuration schema in README.md; update the file with these three
explicit steps so tests won’t fail due to a missing or mislocated configuration
file.


## 6. Project Structure

When adding new features, maintain the existing structure:

* `/api/` - Vercel Functions entry points only
* `/common/` - Shared utilities and base classes
* `/metrics/` - Blockchain-specific metric implementations
* `/tests/` - Test scripts

## 7. Environment Variables

Never commit credentials or secrets. Always use environment variables:

* Development: `.env.local` (git-ignored)
* Production: Configured in Vercel dashboard
* Metrics are automatically prefixed using the `METRIC_PREFIX` constant from `config/defaults.py` which reads `os.getenv("VERCEL_ENV")` (e.g., "dev_" for non-production and "" for production)

---

Following these practices ensures reliable development and prevents disruption to the production monitoring system. When in doubt, test locally before making any deployment-related changes.