docs(inspection): surface existing brain.rules/explain/export API per sim20+sim22 demand#56
Merged
Merged
Conversation
… sim20+sim22 demand Users consistently asked for "git diff for AI preferences" and a way to inspect/export graduated rules (30+ mentions across sim20 and sim22). The API already exists in brain_inspection.py and brain.py — this commit just makes it discoverable. - README.md: new "Inspection & Transparency API" section with one-line description and example for each method (rules, explain, trace, export_data, export_rules, export_rules_json, export_skill, export_tree, pending_promotions, approve_promotion, reject_promotion). - docs/sdk/brain.md: dedicated Inspection & Transparency section with full signatures and return shapes; added the missing export_rules_json, export_skill, export_skills, and export_tree entries; clarified the pre- vs post-graduation distinction between review_pending/approve_lesson and pending_promotions/approve_promotion. No code changes. No new methods. Tests: 2221 passed, 23 skipped. Co-Authored-By: Gradata <noreply@gradata.ai>
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Gradata has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.
📝 Walkthrough
WalkthroughDocumentation updates to introduce and elaborate on rule inspection, traceability, and promotion workflows in the Brain SDK. README reorganizes existing API references to point to a new dedicated section; docs/sdk/brain.md provides comprehensive method signatures and return shapes for rule listing, explanation, tracing, export, and promotion approval/rejection endpoints. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested labels
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/sdk/brain.md`:
- Around line 371-373: Update the docs to match the actual implementation of
brain.export_skill: change the signature to export_skill(self, rule_id: str,
output_file: str = "skill.json", skill_name: str = "") -> str, replace
parameters output_dir/min_state with rule_id and output_file, update the return
type to str, and change the description to "Export a single rule as a skill
definition (JSON)" (reference the export_skill implementation in brain.py).
- Around line 375-377: Update the docs for brain.export_skills to match the
implementation: change the description to state that export_skills (in
brain.export_skills) writes one JSON file per graduated rule (not one SKILL.md
per category), include that files are JSON skill files per rule, and keep that
the method returns the list of written file paths; also update any
signature/parameter notes (output_dir, min_state) to reflect current behavior
and file naming/format (JSON) instead of "SKILL.md".
In `@README.md`:
- Line 234: The README example calls export_skill with output_dir but the actual
method signature is export_skill(self, rule_id: str, output_file: str =
"skill.json", skill_name: str = ""), so update the example to pass a rule_id as
the first argument and optionally output_file/skill_name, or change the example
to use export_skills when demonstrating exporting all rules; reference the
export_skill function and export_skills helper to ensure the example matches the
implementation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: c7585a4c-1f52-480c-bf30-28bf33e44588
📒 Files selected for processing (2)
README.mddocs/sdk/brain.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: test (3.13)
- GitHub Check: test (3.12)
- GitHub Check: test (3.11)
- GitHub Check: Cloudflare Pages
Comment on lines
+371
to
+373
| ### `brain.export_skill(output_dir=None, min_state="PATTERN", skill_name="")` → Path | ||
|
|
||
| Export graduated rules as a full [skill directory](https://github.com/openspace-ai/skills) (SKILL.md + metadata). Returns the path to the created directory. |
There was a problem hiding this comment.
Critical: export_skill signature and description are incorrect.
The documented signature export_skill(output_dir=None, min_state="PATTERN", skill_name="") does not match the actual implementation. According to the source code in brain.py:1234-1238, the actual signature is:
def export_skill(
self, rule_id: str, output_file: str = "skill.json", skill_name: str = ""
) -> str:
"""Export a single rule as a skill definition (JSON)."""Issues:
- Parameters: Should be
rule_id,output_file,skill_name(notoutput_dir,min_state,skill_name) - Return type: Returns
str(notPath) - Description: Exports "a single rule as a skill definition (JSON)" (not "a full skill directory")
📝 Proposed fix
-### `brain.export_skill(output_dir=None, min_state="PATTERN", skill_name="")` → Path
+### `brain.export_skill(rule_id, output_file="skill.json", skill_name="")` → str
-Export graduated rules as a full [skill directory](https://github.com/openspace-ai/skills) (SKILL.md + metadata). Returns the path to the created directory.
+Export a single rule as a skill definition (JSON file). Returns the path to the created file.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/sdk/brain.md` around lines 371 - 373, Update the docs to match the
actual implementation of brain.export_skill: change the signature to
export_skill(self, rule_id: str, output_file: str = "skill.json", skill_name:
str = "") -> str, replace parameters output_dir/min_state with rule_id and
output_file, update the return type to str, and change the description to
"Export a single rule as a skill definition (JSON)" (reference the export_skill
implementation in brain.py).
Comment on lines
+375
to
+377
| ### `brain.export_skills(output_dir=None, min_state="PATTERN")` → list[str] | ||
|
|
||
| Export graduated rules as one SKILL.md per category. Returns the list of files written. |
There was a problem hiding this comment.
Minor: export_skills description is inconsistent with implementation.
The documentation states "Export graduated rules as one SKILL.md per category", but the actual implementation in brain.py:1240-1245 exports "individual skill JSON files" — one JSON file per rule (not per category, and not SKILL.md format).
📝 Proposed fix
-Export graduated rules as one SKILL.md per category. Returns the list of files written.
+Export all graduated rules as individual skill JSON files (one per rule). Returns the list of file paths written.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### `brain.export_skills(output_dir=None, min_state="PATTERN")` → list[str] | |
| Export graduated rules as one SKILL.md per category. Returns the list of files written. | |
| ### `brain.export_skills(output_dir=None, min_state="PATTERN")` → list[str] | |
| Export all graduated rules as individual skill JSON files (one per rule). Returns the list of file paths written. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/sdk/brain.md` around lines 375 - 377, Update the docs for
brain.export_skills to match the implementation: change the description to state
that export_skills (in brain.export_skills) writes one JSON file per graduated
rule (not one SKILL.md per category), include that files are JSON skill files
per rule, and keep that the method returns the list of written file paths; also
update any signature/parameter notes (output_dir, min_state) to reflect current
behavior and file naming/format (JSON) instead of "SKILL.md".
| brain.export_data(output_format="json") # or "yaml" | ||
| brain.export_rules(min_state="PATTERN") # OpenSpace-compatible SKILL.md | ||
| brain.export_rules_json(min_state="RULE") # flat sorted JSON array | ||
| brain.export_skill(output_dir="./skills") # full skill directory |
There was a problem hiding this comment.
Critical: export_skill example uses incorrect signature.
This example call is inconsistent with the actual implementation. According to brain.py:1234-1238, export_skill requires a rule_id as the first parameter, not output_dir:
def export_skill(
self, rule_id: str, output_file: str = "skill.json", skill_name: str = ""
) -> str:The current example will fail at runtime.
🐛 Proposed fix
-brain.export_skill(output_dir="./skills") # full skill directory
+brain.export_skill("rule_abc123", output_file="./skills/rule.json") # single rule as JSONOr if you want to export all rules as individual files, use export_skills:
-brain.export_skill(output_dir="./skills") # full skill directory
+brain.export_skills(output_dir="./skills") # all rules as individual JSON files🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 234, The README example calls export_skill with output_dir
but the actual method signature is export_skill(self, rule_id: str, output_file:
str = "skill.json", skill_name: str = ""), so update the example to pass a
rule_id as the first argument and optionally output_file/skill_name, or change
the example to use export_skills when demonstrating exporting all rules;
reference the export_skill function and export_skills helper to ensure the
example matches the implementation.
Gradata
added a commit
that referenced
this pull request
Apr 15, 2026
…gin/
README:
- Lead with problem framing ("Your AI keeps making the same mistakes")
- 30-second pitch table moved up with vs Mem0 / vs fine-tuning / vs system prompts
- Kept ablation v4 data + Min 2022 random-label control
- Merged new JS/TS (@gradata/cli) and Docker install paths from #80
- Preserved Inspection & Transparency API section from #56
- Tightened features into scannable single-line blocks
- Repo layout + intellectual lineage kept but demoted below primary CTA
.gitignore:
- Add gradata-plugin/ (orphaned clone of separate plugin repo, superseded by
.claude-plugin/ in this repo via #53; can't be rm'd due to OneDrive lock)
Co-Authored-By: Gradata <noreply@gradata.ai>
3 tasks
Gradata
added a commit
that referenced
this pull request
Apr 15, 2026
…gin/ (#84) README: - Lead with problem framing ("Your AI keeps making the same mistakes") - 30-second pitch table moved up with vs Mem0 / vs fine-tuning / vs system prompts - Kept ablation v4 data + Min 2022 random-label control - Merged new JS/TS (@gradata/cli) and Docker install paths from #80 - Preserved Inspection & Transparency API section from #56 - Tightened features into scannable single-line blocks - Repo layout + intellectual lineage kept but demoted below primary CTA .gitignore: - Add gradata-plugin/ (orphaned clone of separate plugin repo, superseded by .claude-plugin/ in this repo via #53; can't be rm'd due to OneDrive lock) Co-authored-by: Gradata <noreply@gradata.ai>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
approve_lesson) vs post-graduation (approve_promotion) approval APIs.Motivation
Rule transparency + inspectability was the #1 user demand across sim20 (30+ mentions) and sim22 (highest-liked comment at 30 likes: "Git diff for AI preferences"). The API already existed in
src/gradata/brain_inspection.pyandsrc/gradata/brain.py— users just couldn't find it.Changes
Follow-ups noted (out of scope for this PR)
docs/api/brain.mdis orphaned (not in mkdocs.yml nav); deletion candidate.brain.explain(),rules(),trace(),export_data()docstrings are one-liners; thin.Test plan
Co-Authored-By: Gradata noreply@gradata.ai