Document activity search filter

[Thanhdn1984]

Refs #426\n\nUpdates the agent guide to show the current search filter alongside the existing accepted-work activity example.\n\nEvidence:\n- registers with optional .\n- passes the query into .\n- filters activity rows by account, amount, submission reference, bounty reference, issue URL, PR URL, proof hash, and note.\n\nValidation:\n- docs smoke ok →

Summary by CodeRabbit

• Documentation
  • Enhanced /api/v1/activity documentation with examples of the q query parameter for activity filtering
  • Added details on supported search fields (account, amount, submission references, URLs, proof hash, notes)
  • Clarified consistent filtering behavior across API and HTML activity pages

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation for the /api/v1/activity endpoint expands to show the optional q query parameter in a curl example and document its text-search behavior over accepted-work row fields including account, amount, submission/bounty references, issue URL, PR URL, proof hash, and note.

Changes

Activity filter query parameter documentation

Layer / File(s)	Summary
Activity filter query parameter documentation docs/agent-guide.md	The /api/v1/activity curl example demonstrates the q filter parameter, and accompanying documentation describes the text-search capability, enumerated match fields (account, amount, submission/bounty references, issue URL, PR URL, proof hash, note), and parity with the /activity HTML page filter.

Possibly related PRs

• ramimbo/mergework#449: Adds /activity search query (q) behavior messaging and tests for query-based empty states.
• ramimbo/mergework#412: Updates /api/v1/activity documentation and tests for the q filter expansion.

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. It is missing the Summary section structure, Evidence subsection clarity, and a properly formatted Test Evidence checklist with actual validation results.	Complete the Summary section, clarify Evidence subsections (currently fragmented), and provide documented test results for all checklist items including the docs smoke validation.
Bounty Pr Focus	⚠️ Warning	Documentation claims note is searchable, but implementation only searches account, amount, submission/PR URL, bounty id/repo, issue URL/number, proof hash.	Remove "or note" from activity filter docs in agent-guide.md lines 71-73 to match actual implementation.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Document activity search filter' is concrete and directly names the changed surface, matching the requirement.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	No investment, price, cash-out, fabricated payout, or private security detail claims found in docs. MRWK described appropriately in technical terms only.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c961918a-a242-430a-a5ba-96f0bc57bb34

📥 Commits

Reviewing files that changed from the base of the PR and between d8532d4 and 3c5ad36.

📒 Files selected for processing (1)

• docs/agent-guide.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Remove unsupported note filter claim from /api/v1/activity docs.

The implementation does not search a note field. Current matching is against account, amount_mrwk, submission_url, proof_hash, bounty_id, bounty_repo, bounty_issue_url, and bounty_issue_number (app/serializers.py, _activity_row_matches). Please update this sentence to avoid documenting behavior that does not exist.

Proposed doc fix

-`/api/v1/activity` accepts optional `q` text search. It filters accepted-work
-rows by account, amount, submission reference, bounty reference, issue URL, PR
-URL, proof hash, or note; the HTML `/activity` page uses the same filter.
+`/api/v1/activity` accepts optional `q` text search. It filters accepted-work
+rows by account, amount, submission/PR reference, bounty id or repo, issue URL
+or issue number, and proof hash; the HTML `/activity` page uses the same filter.

As per coding guidelines, docs under docs/**/*.md must be short, concrete, and avoid unsupported/speculative claims.

[adliebe]

Reviewed PR #536 at current head 3c5ad3675f93309018a5615ad1cf8e8512fccd60 as a non-author.

Scope checked:

• docs/agent-guide.md adds the read-only example curl -s "$API_HOST/api/v1/activity?q=<account-or-pr-or-proof>".
• The guide now explains that /api/v1/activity filters accepted-work rows by account, amount, submission reference, bounty reference, issue URL, PR URL, proof hash, or note, and that the HTML /activity page uses the same filter.

Implementation/evidence checked:

• app/activity.py exposes q: str | None = Query(None) on both /api/v1/activity and /activity, and passes it into activity_context(session, q).
• app/serializers.py normalizes the query and matches it against the documented row fields.
• Existing tests/test_activity.py covers API query filtering and HTML /activity?q=... behavior.
• Existing docs/api-examples.md already documents /api/v1/activity?q=p3xill and the query field set, so the agent guide now aligns with the API examples.

Validation:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_agent_guide_documents_activity_endpoint -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_activity.py::test_activity_api_filters_accepted_work_by_query tests/test_activity.py::test_activity_page_renders_empty_and_paid_states -q -> 2 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev ruff check docs/agent-guide.md app/activity.py app/serializers.py tests/test_activity.py tests/test_docs_public_urls.py -> passed
• uv run --extra dev ruff format --check app/activity.py app/serializers.py tests/test_activity.py tests/test_docs_public_urls.py -> passed
• git diff --check origin/main...HEAD -> clean
• GitHub Quality, readiness, docs, and image checks -> success
• CodeRabbit status -> success

Verdict: approved. The change is small, matches existing route behavior, and improves agent discoverability without adding payout, off-ramp, private credential, or price-claim language.

[weilixiong]

QUALITY_GATE: LOW risk ✅

1 file, +5/-0: Documents the q text search filter on /api/v1/activity in agent-guide.md. Adds endpoint example curl and a 2-line description paragraph.

• docs/agent-guide.md: +5/-0 (activity?q= curl example, filter description)

Verification: pytest tests/test_docs_public_urls.py -k activity → 2/2 passed. docs_smoke.py → ok (RC=0).

Docs-only change, single file, no functional code.

[Juanpablo24-06]

Reviewed PR #536 at current head 3c5ad3675f93309018a5615ad1cf8e8512fccd60 as non-author Juanpablo24-06.

I found one docs/implementation mismatch that should be fixed before merge: the new agent-guide paragraph says /api/v1/activity filters accepted-work rows by note, but the actual activity search path does not include proof note metadata.

Evidence checked:

• The PR diff only changes docs/agent-guide.md and adds the phrase "proof hash, or note" to the activity search description.
• app/activity.py passes q through to activity_context(session, q) / activity_to_dict(session, q).
• app/serializers.py::_activity_row() builds rows from account, amount, submission URL, bounty repo/issue/id, and proof hash, but does not expose verifier_result.note from the proof payload.
• app/serializers.py::_activity_row_matches() searches only account, amount, submission URL, proof hash, bounty id, bounty repo, bounty issue URL, and bounty issue number.
• Existing tests/test_activity.py::test_activity_api_filters_accepted_work_by_query covers account, repo, proof hash, and no-match behavior, but not note search.

Validation run locally:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_activity.py::test_activity_api_filters_accepted_work_by_query -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev ruff check app/serializers.py app/activity.py tests/test_activity.py docs/agent-guide.md -> passed

Suggested fix: remove or note from the new agent-guide sentence, or extend the implementation/tests to actually include proof notes in activity search. For this docs-only PR, removing the note claim is the smaller scoped fix.

[tolga-tom-nook]

Reviewed PR #536 at current head 3c5ad367 for the rolling review bounty #447.

I checked the docs-only diff in docs/agent-guide.md against the current implementation in app/activity.py and app/serializers.py, then ran:

• python3 scripts/docs_smoke.py -> docs smoke ok
• python3 -m pytest tests/test_docs_public_urls.py::test_agent_guide_documents_activity_endpoint tests/test_activity_routes.py -q -> 2 passed

Requesting one small correction before merge: the new sentence says /api/v1/activity?q=... filters by "note", but _activity_row_matches() only searches account, amount_mrwk, submission_url, proof_hash, bounty_id, bounty_repo, bounty_issue_url, and bounty_issue_number. The payout verifier note can exist in proof metadata, but it is not exposed in _activity_row() or included in the searchable tuple. Please either remove "note" from the documented filter list or add it to the activity row/search behavior with test coverage.

[eliasx45]

I found one blocker on current head 3c5ad3675f93309018a5615ad1cf8e8512fccd60.

The new agent-guide text says /api/v1/activity?q=... filters accepted-work rows by note, but the implementation does not search proof/verifier notes. _activity_row() builds rows with account, amount, submission URL, bounty repo/issue/id/URL, proof hash/URL, and timestamps; _activity_row_matches() searches only account, amount, submission URL, proof hash, bounty id, bounty repo, bounty issue URL, and bounty issue number. No proof verifier_result.note value is exposed in the row or included in the searchable tuple.

Please either remove or note from the docs, or add note to the activity row/search behavior with regression coverage.

Evidence checked:

• PR diff is docs-only in docs/agent-guide.md and adds proof hash, or note to the activity search description.
• app/activity.py passes q into activity_to_dict(session, q).
• app/serializers.py::_activity_row() does not expose proof/verifier note metadata.
• app/serializers.py::_activity_row_matches() does not search any note field.
• Existing tests/test_activity.py::test_activity_api_filters_accepted_work_by_query covers account/repo/proof/no-match behavior, not notes.

Validation I ran:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .\.venv\Scripts\python.exe -m pytest tests\test_docs_public_urls.py::test_agent_guide_documents_activity_endpoint tests\test_activity.py::test_activity_api_filters_accepted_work_by_query -q -> 2 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .\.venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok
• .\.venv\Scripts\python.exe -m ruff check tests\test_docs_public_urls.py tests\test_activity.py app\serializers.py app\activity.py -> passed
• .\.venv\Scripts\python.exe -m ruff format --check tests\test_docs_public_urls.py tests\test_activity.py app\serializers.py app\activity.py -> 4 files already formatted
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .\.venv\Scripts\python.exe -m mypy app\activity.py app\serializers.py -> success
• git diff --check origin/main...HEAD -> clean

[ramimbo]

Holding with mrwk:needs-info. The accepted review found the docs say activity search includes note metadata, but the current implementation does not expose or search notes. Please remove that claim or implement and test note search.