Skip to content

Add read-only recent and get CLI commands - #85

Merged
roli-lpci merged 2 commits into
hermes-labs-ai:mainfrom
GaoYqqqq:feat/83-cli-browse-commands
Oct 2, 2026
Merged

roli-lpci merged 2 commits into
hermes-labs-ai:mainfrom
GaoYqqqq:feat/83-cli-browse-commands

Conversation

@GaoYqqqq

@GaoYqqqq GaoYqqqq commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • add fidelis recent with a bounded limit, existing kind/since filters, and raw JSON output
  • add fidelis get RECORD_ID with human-readable temporal and correction-chain metadata
  • preserve structured service errors so unavailable services and unknown records exit explicitly
  • document the commands and add an Unreleased changelog entry

Testing

  • python -m pytest tests/test_cli_browse.py tests/test_mcp_surface_v2.py tests/test_write_fallback_contract.py -q — 74 passed
  • python -m ruff check src/ tests/
  • git diff --check

Closes #83

Summary by Sourcery

Add read-only CLI browsing for recent memories and individual records with correction metadata, raw output, bounded filtering, and explicit error handling.

New Features:

  • Add read-only recent and get CLI commands for browsing records, filtering recent results, and retrieving correction chains.
  • Support human-readable and raw JSON output for both browsing commands.

Bug Fixes:

  • Preserve structured service errors so unavailable services, invalid requests, and unknown records produce explicit nonzero failures.

Enhancements:

  • Bound recent-result limits to 1–50 and expose kind and timestamp filters.
  • Display temporal status, source, timestamps, and correction-chain metadata in human-readable record output.

Documentation:

  • Document the new read-only CLI commands and their options in the full reference.
  • Add an Unreleased changelog entry for the browsing commands and explicit failure behavior.

Tests:

  • Add CLI coverage for browsing options, metadata rendering, raw payloads, structured HTTP errors, service failures, unknown records, and limit validation.

@sourcery-ai

sourcery-ai Bot commented Oct 1, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

This PR adds server-backed, read-only recent and get CLI commands with bounded filtering, human-readable temporal/correction metadata, raw JSON support, and explicit structured error handling, backed by focused tests and documentation.

Sequence diagram for read-only CLI browsing

sequenceDiagram
    actor User
    participant CLI as fidelis CLI
    participant Server as fidelis-server

    alt recent
        User->>CLI: recent --limit --kind --since [--raw]
        CLI->>Server: POST /recent
        Server-->>CLI: records or error
    else get
        User->>CLI: get RECORD_ID [--raw]
        CLI->>Server: POST /get
        Server-->>CLI: record and correction chain or error
    end
    alt service error or unknown record
        CLI-->>User: explicit error and nonzero exit
    else raw output
        CLI-->>User: JSON payload
    else human-readable output
        CLI-->>User: formatted record metadata
    end
Loading

Flow diagram for bounded recent command

flowchart LR
    A[Parse recent options] --> B{limit from 1 to 50}
    B -->|invalid| C[Argument error]
    B -->|valid| D[POST /recent]
    D --> E{error in response}
    E -->|yes| F[Print error and exit nonzero]
    E -->|no| G{--raw}
    G -->|yes| H[Print JSON payload]
    G -->|no| I[Print records with filters and metadata]
Loading

File-Level Changes

Change Details Files
Added read-only CLI commands for bounded recent-record listing and record lookup with correction-chain rendering.
  • Added recent options for limit, kind, since, and raw JSON output.
  • Added get RECORD_ID with human-readable temporal metadata and both correction-chain directions.
  • Registered both commands in the CLI parser and usage text.
src/fidelis/cli.py
docs/full-reference.md
Improved CLI handling of service responses so structured server failures remain actionable.
  • Preserved JSON error bodies from HTTP failures instead of converting them to generic errors.
  • Added explicit nonzero handling for unavailable services, invalid requests, and unknown records.
  • Supported raw JSON output for successful and failing browse requests.
src/fidelis/cli.py
tests/test_cli_browse.py
Added regression coverage for command routing, formatting, bounds, raw responses, and failure behavior.
  • Tested recent filters and metadata rendering.
  • Tested get output, correction chains, raw payloads, and unknown-record failures.
  • Tested structured HTTP errors, service unavailability, and limit validation.
tests/test_cli_browse.py
Documented the new read-only commands and recorded the change in project release notes.
  • Documented server requirements, examples, option bounds, output fields, and failure semantics.
  • Added an Unreleased changelog entry.
docs/full-reference.md
CHANGELOG.md

Assessment against linked issues

Issue Objective Addressed Explanation
#83 Add a read-only fidelis recent CLI command that routes through /recent, supports bounded limits, existing kind and since filters, human-readable metadata, and optional raw JSON output. ✅
#83 Add a read-only fidelis get RECORD_ID CLI command that routes through /get, displays record, temporal, and correction-chain information, and supports optional raw JSON output. ✅
#83 Provide explicit nonzero failures for unavailable services, invalid requests, and unknown records, while documenting and testing the new CLI behavior without direct store access. ✅

Possibly linked issues


Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@coderabbitai

coderabbitai Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 927c64c6-987f-4c99-b278-a392c694f22d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

@roli-lpci roli-lpci left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for adding the bounded recent/get browsing commands and coverage. I reviewed the full diff at 9a361da and the unchanged CI workflow. The fork workflow is suitable to run, but the shared HTTP error handling introduces the regression below, which needs fixing before merge. Please add coverage for an existing read command receiving an HTTP error as well as the new browsing commands.

Reviewed by a Hermes Labs agent at the maintainer’s direction.

Comment thread src/fidelis/cli.py
@GaoYqqqq
GaoYqqqq force-pushed the feat/83-cli-browse-commands branch from d293096 to 0fd1459 Compare October 1, 2026 08:52

@roli-lpci roli-lpci left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks @GaoYqqqq — the opt-in structured error handling addresses the requested regression. I reviewed the complete four-file diff at 0fd1459 and independently checked HTTP 503 behavior for query, recall, recent, and get in both normal and raw modes: all eight checks exit 1, existing commands do not report an empty successful result, and the new raw modes retain the structured error payload. The query regression tests cover normal/raw modes. No further source changes are requested by this review.

I approved the new fork CI run; the full matrix/build checks still need to pass before merge acceptance.

Reviewed by a Hermes Labs agent at the maintainer’s direction.

@roli-lpci
roli-lpci merged commit 47b88a2 into hermes-labs-ai:main Oct 2, 2026
13 checks passed
@roli-lpci

Copy link
Copy Markdown
Member

Thanks @GaoYqqqq — merged as 47b88a2, closing #83. Your bounded read-only CLI commands meet the issue criteria, and the opt-in structured error handling preserves failures for existing commands. All ten Python/OS CI matrix jobs and the package build passed on 0fd1459. Matching local Gate fast and technical review receipts passed with no findings; the installed Gate used its validated hermes-pr-review fallback after CodeRabbit, and an independent steward accepted the exact head before the guarded merge.

Reviewed by a Hermes Labs agent at the maintainer’s direction.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add read-only fidelis recent and fidelis get CLI commands

2 participants