v0.6.0: open-source pivot (Apache + cloud algorithms merged into SDK)#93
Merged
v0.6.0: open-source pivot (Apache + cloud algorithms merged into SDK)#93
Conversation
Strategic pivot: open-source everything, monetize hosted SaaS. The moat is not the algorithm code (publishable, reproducible) but the hosted team cloud + opt-in corrections corpus + brain marketplace. Apache-2.0 unblocks enterprise adoption, removes linking concerns, and matches the ecosystem norm for OSS infra (LangChain, Supabase, PostHog). - LICENSE: AGPL-3.0 (674 lines) -> Apache-2.0 (213 lines) - pyproject.toml: license field + OSI classifier - README: badge, tagline, license section (new BSL-free framing) - src/gradata/_core.py: manifest template string - SPDX headers in 2 detection/ files Sole author (Oliver); unilateral relicense is legally valid. Co-Authored-By: Gradata <noreply@gradata.ai>
…its, profiling) Previously proprietary algorithms are now part of the free SDK. Matches the pivot: the product is the hosted SaaS (team cloud + corpus + marketplace), not code secrecy. Merged from private gradata_cloud_backup/ snapshot: - enhancements/graduation/ (3 files): agent_graduation, judgment_decay, rules_distillation - enhancements/scoring/ (9 files): brain_scores, calibration, correction_tracking, failure_detectors, gate_calibration, loop_intelligence, memory_extraction, reports, success_conditions - enhancements/bandits/ (2 files): contextual_bandit, collaborative_filter - enhancements/profiling/ (1 file): tone_profile (universal style extraction) - examples/domain-profiles/ (2 files): call_profile, sales_profile (recipes for domain builders, not SDK primitives) Skipped 5 duplicate files (SDK versions are current — e.g. carl.py is explicitly v2 of backup; self_improvement.py grew 2.5x past backup). API drift fixes: - gradata_cloud.scoring.metrics -> gradata.enhancements.metrics (3 files) - .self_improvement -> gradata.enhancements.self_improvement (2 files) - .._events -> gradata._events (1 file) - MetricsWindow.avg_edit_distance -> edit_distance_avg (API rename) - Added format_metrics() to enhancements/metrics.py (ported from backup) - Added get_maturity_phase() to enhancements/self_improvement.py Zero new required dependencies (all 17 files pure stdlib). Tests: 2561 passed, 24 skipped (cloud-gated skips still present — next task is un-skip). Co-Authored-By: Gradata <noreply@gradata.ai>
Modules now exist in SDK, so skip guards on these are obsolete: - test_agent_graduation.py: remove file-level cloud import guard - test_brain.py: remove TestCoreLearningLoop skip - test_spawn_extraction.py: remove self_improvement + agent_graduation guards - test_coverage_gaps.py, test_enhancements.py, test_spec_compliance.py: remove module-level importorskip - test_bug_fixes.py::test_compute_density_importable: remove skipif Import path updates (nested structure per architect council): - gradata.enhancements.agent_graduation -> gradata.enhancements.graduation.agent_graduation API drift xfail markers (reconcile in v0.7): - test_lesson_graduates_to_pattern: ACCEPTANCE_BONUS constant changed - test_rejection_decreases_confidence: rejection sign convention changed Results: 2561 -> 2598 passed (+37), 24 -> 19 skipped, 2 xfailed. Remaining skips are legitimate (cloud-only meta_rules flat module, external API tests). Co-Authored-By: Gradata <noreply@gradata.ai>
Consolidate to one install path: `pip install gradata && gradata hooks install`. The npm wrapper created parallel install surfaces that confused the "Python SDK, one command" messaging Oliver wants. Changes: - gradata-install/package.json: license -> Apache-2.0, add npm deprecated field, version bump to 0.6.0, updated description. - gradata-install/bin/gradata-install.js: add deprecation notice at top that prints to stderr on every invocation. Core functionality preserved for backcompat with users who've pinned `npx gradata-install`. - gradata-install/README.md: full rewrite around deprecation + redirect to `pip install gradata`. Multi-IDE support (cursor, codex, gemini-cli, continue) deferred: users who need those should open an issue and we'll add the installer to the main gradata Python package. Not reimplementing 337 lines of JS for hypothetical users. Co-Authored-By: Gradata <noreply@gradata.ai>
First piece of cloud integration wire. Lets users opt into: - Metrics sync to cloud dashboard (fitness tracker view) - Managed LLM synthesis (skip BYOK) - Future: team brain, corrections corpus contribution, marketplace Privacy model: - OFF by default. Nothing leaves the brain without explicit enable. - Metrics payload contains NO correction content — only aggregated MetricsWindow fields (session count, rule counts, rewrite rate, blandness score, correction density). - Corpus contribution is a SEPARATE opt-in flag, stricter gate: requires BOTH sync_enabled AND contribute_corpus. - All HTTP failures are silent (cloud sync must never block learning loop). Wire protocol: - POST https://api.gradata.ai/v1/telemetry/metrics (metrics) - POST https://api.gradata.ai/v1/corpus/contribute (corpus, separate opt-in) - Bearer token auth via Gradata API token - Zero new dependencies: urllib + json only Config persistence: - Per-brain: brain_dir/cloud-config.json - Fields: sync_enabled, token, api_base, contribute_corpus, last_sync_at - Corrupt config falls back to defaults (never raises) Tests: 17/17 passing. Covers disabled-by-default, roundtrip config, enable gates, success/failure paths, corpus-requires-both-flags, never-raises contract. Co-Authored-By: Gradata <noreply@gradata.ai>
Document the strategic pivot: AGPL->Apache relicense, cloud algorithms merge into SDK, opt-in cloud sync client, product positioning around hosted SaaS (not code secrecy). Co-Authored-By: Gradata <noreply@gradata.ai>
Content pivot: moat is hosted SaaS (team cloud + corpus + marketplace), not code secrecy. Apache-2.0 maximizes distribution. Cloud tier is value-add service, not gated code. 11 files updated + 1 npm package.json license field. Co-Authored-By: Gradata <noreply@gradata.ai>
# Conflicts: # gradata-install/README.md
Previous copy still referenced BSL-1.1 for cloud — that was a middle-ground option superseded by the decision to keep Gradata Cloud as a fully private hosted SaaS (not open-sourced at all). Cleaner messaging: Apache SDK = free full product. Cloud = optional hosted service. No "self-host the cloud code" path — Cloud is a service, not a repo. 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.
📝 WalkthroughSummaryLicense & Strategic Shift
Breaking Changes
New SDK Surface
Documentation & Configuration
Test Coverage
WalkthroughVersion 0.6.0 release transitioning licensing from AGPL-3.0-or-later to Apache-2.0, introducing opt-in cloud telemetry sync, deprecating the npm installer in favor of Python CLI, and adding extensive enhancement modules for agent graduation, behavioral profiling, scoring/calibration, and collaborative filtering. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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: 55
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CHANGELOG.md`:
- Around line 50-54: Update the stale test count in the 0.6.0 changelog entry:
locate the string "**2598 tests passing**" in CHANGELOG.md and change it to
"**2615 tests passing**" (and scan the same 0.6.0 notes for any other
occurrences of 2598 to keep numbers consistent with the release
notes/objectives).
In `@docs/faq.md`:
- Around line 5-7: The FAQ wording contradicts the implementation in
src/gradata/cloud/sync.py: update docs/faq.md to state the actual sync privacy
model used by sync.py — telemetry is metrics-only by default and raw
correction/corpus data is only transmitted if the user explicitly opts into
corpus sync (corpus opt-in), and that Cloud remains optional/locally-operable
(BYOK). Reference the metrics-only default and corpus opt-in behavior from
src/gradata/cloud/sync.py in the text and remove any blanket statement that raw
correction text is sent by default when sync is enabled.
In `@docs/index.md`:
- Line 12: In the tagline string "One brain, many hosts. Open source SDK
(Apache-2.0), optional hosted cloud at [gradata.ai](https://gradata.ai)."
replace the unhyphenated compound adjective "Open source SDK" with the
hyphenated form "Open-source SDK" so the sentence reads "One brain, many hosts.
Open-source SDK (Apache-2.0), optional hosted cloud at
[gradata.ai](https://gradata.ai)."
In `@docs/RELEASE-v0.5.0-DRAFT.md`:
- Line 84: The release note text currently reads "Apache-2.0. Full text in
`LICENSE`. See `docs/LICENSING.md` — SDK is permissively open, hosted SaaS at
gradata.ai is the paid tier." but v0.5 is AGPL; update that sentence to state
"AGPL-3.0" (or "AGPL-3.0-or-later" as your policy requires) and ensure the
reference to `LICENSE` and `docs/LICENSING.md` accurately reflect the AGPL
license for v0.5; search for the exact sentence in the v0.5 release note and
replace it so the release note, the `LICENSE` reference, and any mention of the
SDK/licensing in `docs/LICENSING.md` consistently indicate AGPL for v0.5.
In `@pyproject.toml`:
- Around line 7-10: The pyproject.toml still declares the old version string;
update the version metadata by changing the version = "0.5.0" entry to the
correct release version (e.g., version = "0.6.0") so package artifacts and
metadata match this release; locate the version field in pyproject.toml (the
version = "...") and update it accordingly before publishing.
In `@src/gradata/cloud/sync.py`:
- Around line 37-41: The cloud sync config currently persists a secret (the
`token` field) in `sync_enabled: bool = False` / `token: str = ""` and later
blocks (also at the analogous 67-73 area); remove the persistent `token`
property from the stored config and ensure code paths that read `token` instead
obtain it from the environment or the existing secret-loading helpers used in
`src/gradata/_config.py` and `src/gradata/cloud/client.py` (e.g., switch callers
that reference the `token` attribute to call the env/secret accessor), leaving
only non-secret flags/state (like `sync_enabled`, `api_base`,
`contribute_corpus`, `last_sync_at`) in the JSON representation.
- Around line 118-127: The _post method currently attaches Authorization using
self.config.token to any config.api_base; validate the target before sending by
parsing self.config.api_base (use urllib.parse.urlparse) and ensure the scheme
is "https" and the netloc/hostname is in the same trusted-hosts check used
elsewhere (mirror the logic from src/gradata/cloud/client.py or
src/gradata/integrations/embeddings.py); if the scheme is not https or the host
is not allowed, raise an exception or refuse to attach the Authorization header
and abort the request. Locate the URL construction and header assembly in _post
and add this validation step before creating the urllib.request.Request.
- Around line 138-149: sync_metrics currently uses payload.sent_at as part of
the server dedup key which changes on retries; change to send or include a
stable idempotency key so retries are deduplicated. Modify sync_metrics (and the
TelemetryPayload or caller) to include a stable idempotency_id (e.g., a UUID
generated when the event/session is created or use the immutable pair (brain_id,
session)) and send that instead of relying on sent_at; ensure the server-side
dedup key uses idempotency_id (or brain_id+session) while preserving sent_at as
a timestamp only, and update save_config(self.brain_dir, self.config) behavior
to still record last_sync_at from payload.sent_at after a successful POST.
In `@src/gradata/enhancements/bandits/__init__.py`:
- Line 1: The module src/gradata/enhancements/bandits/__init__.py is missing the
required future annotations import; add the statement from __future__ import
annotations at the top of this module (before any other code or docstring) so
the file complies with the project-wide typing rule for src/gradata/**/*.py and
ensures annotations in this package (bandits module and any symbols defined or
re-exported here) use postponed evaluation.
In `@src/gradata/enhancements/bandits/collaborative_filter.py`:
- Around line 148-159: The loop applies TransferRecommendation fields directly
and can reduce or over-inflate lesson.confidence; clamp
rec.source_brain_similarity and rec.transfer_boost to the [0.0, 1.0] range
before using them in the boost calculation (e.g., normalize both to
min(max(value, 0.0), 1.0)), compute boost = min(clamped_transfer_boost *
clamped_source_brain_similarity, max_boost), then add to lesson.confidence while
ensuring lesson.confidence remains within [0.0, 1.0] (and still respect the
existing cap below RULE such as 0.89).
In `@src/gradata/enhancements/bandits/contextual_bandit.py`:
- Around line 192-201: The load_arms method currently trusts persisted values
for alpha, beta, and context_scores which can break sampling and scoring; update
load_arms to validate the incoming values for RuleArm creation: ensure alpha and
beta are > 0 (either clamp to a minimum like 1e-6 or raise a ValueError) and
ensure every context_scores value is within [0.0, 1.0] (either clamp or reject),
and if you choose to clamp, document defaults used; make these checks where
RuleArm(...) is constructed so sample() and the blending logic that uses
context_scores are safe.
In `@src/gradata/enhancements/graduation/agent_graduation.py`:
- Line 823: The return type for enforce_rules is using a string literal; change
def enforce_rules(self, agent_type: str, output: str, task_type: str = "") ->
"EnforcementResult": to use the actual type (-> EnforcementResult) instead of a
quoted forward reference, and ensure EnforcementResult is available (either
import/define EnforcementResult in this module or add from __future__ import
annotations at the top to allow forward references). Update the signature in the
enforce_rules method accordingly and fix any missing imports or definitions for
EnforcementResult.
- Line 453: Replace the explicit timezone.utc usage when generating today's
date: in the call to datetime.now (the expression
datetime.now(timezone.utc).strftime("%Y-%m-%d")), use the datetime.UTC alias
instead (i.e., datetime.now(datetime.UTC).strftime(...)) so the code uses the
standardized UTC alias; update any import if needed to reference datetime.UTC
alongside the existing datetime.now usage.
- Line 776: The return type on get_deterministic_rules uses a quoted forward
reference "DeterministicRule"; remove the quotes and use a native typed
annotation list[DeterministicRule] instead (i.e., change def
get_deterministic_rules(... ) -> list["DeterministicRule"] to ->
list[DeterministicRule]) so it relies on from __future__ import annotations;
update only the annotation on the get_deterministic_rules function signature.
- Around line 252-253: The _now function should use the new datetime.UTC alias
instead of timezone.utc; update the call in _now() to
datetime.now(datetime.UTC).isoformat() and adjust imports if necessary (remove
or stop using timezone) so the function uses datetime.UTC consistently;
reference: function _now in agent_graduation.py.
- Around line 46-68: The import block in agent_graduation.py is not sorted (Ruff
I001); reorder imports so they follow standard grouping and alphabetical order:
keep "from __future__ import annotations" first, then standard library imports
(json, re, dataclasses, datetime, pathlib) alphabetized, then a blank line, then
the local package import from gradata.enhancements.self_improvement with its
symbols (SURVIVAL_BONUS, ACCEPTANCE_BONUS, MISFIRE_PENALTY, PATTERN_THRESHOLD,
RULE_THRESHOLD, MIN_APPLICATIONS_FOR_PATTERN, MIN_APPLICATIONS_FOR_RULE,
LessonState, Lesson, parse_lessons, format_lessons, get_maturity_phase) sorted
alphabetically in the parentheses; run isort/ruff or manually apply this
ordering so the import block passes the linter.
In `@src/gradata/enhancements/graduation/judgment_decay.py`:
- Around line 32-41: The import block is unsorted causing Ruff I001; reorder
imports into the canonical groups and alphabetical order: keep "from __future__
import annotations" first, then standard-library imports ("from dataclasses
import dataclass" and "from typing import Any" alphabetized), followed by a
blank line and then the local package import "from
gradata.enhancements.self_improvement import Lesson, LessonState,
PATTERN_THRESHOLD" with its names alphabetized; ensure single blank lines
between groups to satisfy import sorting rules.
In `@src/gradata/enhancements/metrics.py`:
- Around line 122-133: Add explicit input typing to the public formatter by
annotating the parameter of format_metrics to accept either a MetricsWindow
instance or a mapping/dict (e.g. m: Union["MetricsWindow", Mapping[str, Any]] ->
str) and import required typing names (Union, Mapping, Any) so callers and
linters get strong types; also ensure the file starts with from __future__
import annotations so the forward reference "MetricsWindow" works. Keep the
inner helper get signature as is but use the typed m to drive getattr/mapping
access and update any references to compute_metrics return types if needed to
match the new annotation.
- Around line 150-157: format_metrics currently defaults missing numeric metrics
to 0.0 causing misleading output; change the formatting so that rewrite_rate,
rule_success_rate, rule_misfire_rate (and any other optional fields like
edit_avg) are only formatted as percentages/numbers when their keys exist in the
metrics dict (or are not None), otherwise render a clear placeholder such as
"n/a" or "none". Locate the lines building the output (the f-strings referencing
get('rewrite_rate', 0.0), get('rule_success_rate', 0.0),
get('rule_misfire_rate', 0.0), and edit_avg) and replace them with conditional
formatting: check presence (e.g., "if 'rewrite_rate' in metrics" or use
metrics.get('rewrite_rate') is not None) and format with "{:.1%}".format(value)
when present, otherwise insert "n/a" (and likewise for edit_avg use "{:.2f}"
when present else "n/a").
In `@src/gradata/enhancements/profiling/__init__.py`:
- Line 1: This module is missing the mandatory future import for postponed
annotations; add the line "from __future__ import annotations" as the first
statement after the module-level docstring in the profilng package initializer
(the profiling/__init__.py module) so that type annotations are treated as
strings at runtime; ensure the import appears before any other code or imports
in that module.
In `@src/gradata/enhancements/profiling/tone_profile.py`:
- Around line 120-124: The return type annotation on ToneFeatures.from_dict is a
quoted forward-reference; remove the quotes so the signature reads def
from_dict(cls, d: dict[str, Any]) -> ToneFeatures:. Also ensure from __future__
import annotations is present at the top of the module so forward references are
supported; update the method signature in the ToneFeatures class accordingly.
- Around line 252-261: The type annotation for the classmethod return in
ToneProfile.from_dict uses an unnecessary forward-reference string
("ToneProfile"); update the signature to use the actual class type without
quotes by changing def from_dict(cls, d: dict[str, Any]) -> ToneProfile, and
ensure imports/types (ToneProfile, ToneFeatures) are in scope so the annotation
resolves correctly; keep the rest of the method (features =
ToneFeatures.from_dict...) unchanged.
- Around line 30-34: Reorder and format the import block in tone_profile.py to
satisfy Ruff I001: group imports into stdlib, third-party, and local (here only
stdlib/typing/dataclasses) and sort alphabetically within each group;
specifically ensure "from __future__ import annotations" stays first, then
alphabetically order the stdlib imports (e.g., import re), then the
dataclasses/typing imports sorted (e.g., from dataclasses import dataclass,
field before/after from typing import Any as needed to be alphabetical), and
ensure there is a blank line between groups.
In `@src/gradata/enhancements/scoring/__init__.py`:
- Line 1: The module is missing the required future import for postponed
evaluation of annotations; add the line "from __future__ import annotations" at
the very top of the module (before the module docstring in
src/gradata/enhancements/scoring/__init__.py) so the module-level docstring and
any annotations in this package comply with the project's type-safety standard.
In `@src/gradata/enhancements/scoring/brain_scores.py`:
- Around line 24-27: Remove the no-op TYPE_CHECKING block and the now-unused
import: delete the "from typing import TYPE_CHECKING" line and the "if
TYPE_CHECKING: pass" block in brain_scores.py so the empty conditional and
unused symbol are gone (clean up any related imports or comments if present).
In `@src/gradata/enhancements/scoring/calibration.py`:
- Around line 80-82: Add validation in the class __init__ to reject non-positive
bin counts: check that the n_bins argument is an integer greater than 0 and if
not raise a ValueError with a clear message (e.g., "n_bins must be a positive
integer"); set self._n_bins only after the check so subsequent compute() logic
that uses self._n_bins (and bin_width = 1.0 / self._n_bins) cannot divide by
zero or behave unexpectedly.
- Around line 95-97: The load() method currently appends raw prediction tuples
to self._predictions and can violate the invariant that confidence values are in
[0.0, 1.0]; update load() to normalize inputs before storing by either iterating
over the incoming predictions and calling the existing record(pred_conf,
outcome) for each pair, or clamp each confidence with confidence = max(0.0,
min(1.0, float(confidence))) and coerce outcome to bool before extending
self._predictions, so all stored entries follow the same [0.0,1.0] guarantee
used by record(), Brier/ECE, and binning logic.
In `@src/gradata/enhancements/scoring/correction_tracking.py`:
- Around line 18-21: Remove the unused TYPE_CHECKING block: delete the "from
typing import TYPE_CHECKING" import and the empty "if TYPE_CHECKING: pass"
conditional in correction_tracking.py (remove the TYPE_CHECKING symbol usage
entirely since the block is empty).
- Around line 449-455: compute_density currently declares db_path: Path | None =
None but calls compute_correction_profile(db_path=...) which expects a Path,
causing type/runtime errors; fix by either making compute_density's db_path
parameter required (change signature to db_path: Path) or resolve a concrete
Path inside compute_density before delegating (e.g., call your project’s
existing default DB path helper and pass that Path into
compute_correction_profile), and update the docstring/type hints accordingly so
compute_correction_profile always receives a Path.
- Around line 358-361: The code currently forces total_sessions_in_window =
max(1, max_session - min_session + 1), which invents a session for empty
windows; instead compute the raw span (span = max_session - min_session + 1) and
set total_sessions_in_window = span if span > 0 else 0 so empty windows yield 0
and let compute_mtbf_mttr(correction_session_list, total_sessions_in_window)
return the documented zero/empty fallback; update the assignment to use these
variables (referencing total_sessions_in_window, max_session, min_session,
correction_session_list, and compute_mtbf_mttr).
In `@src/gradata/enhancements/scoring/failure_detectors.py`:
- Around line 225-245: In detect_regression_to_mean(), the alert payload
hardcodes "0.70" instead of using the configurable blandness_warn (and
blandness_critical) values; update the evidence["threshold"] to use
blandness_warn (and optionally include blandness_critical) and change the Alert
message to interpolate blandness_warn (e.g., format to three decimals) so the
reported threshold matches the actual parameter; reference symbols:
detect_regression_to_mean, current.blandness_score, blandness_warn,
blandness_critical, evidence, and the Alert(...) message construction.
- Around line 23-26: Add the missing future annotations import by adding "from
__future__ import annotations" at the top of the module, and update
detect_regression_to_mean to use the blandness_warn parameter (not the hardcoded
0.70) wherever the threshold is reported: replace the literal 0.70 in the
evidence dict and in the alert message generation with the blandness_warn
variable so the evidence["threshold"] and the alert text reflect the configured
value.
In `@src/gradata/enhancements/scoring/gate_calibration.py`:
- Line 34: The import statement currently brings in an unused symbol `field`
from dataclasses (see the line importing "dataclass, field"); remove `field`
from the import so it reads only `from dataclasses import dataclass` to
eliminate the unused import warning and pipeline failure.
In `@src/gradata/enhancements/scoring/loop_intelligence.py`:
- Around line 440-466: The parameter type hint for positive_outcomes in
aggregate_by_key should use the modern union syntax; replace Optional[set[str]]
with set[str] | None in the function signature (i.e., positive_outcomes:
set[str] | None = None) and keep the runtime logic that falls back to
_POSITIVE_OUTCOMES unchanged; update only the annotation (and add or ensure any
necessary Python version compatibility imports if your codebase targets
pre-3.10).
- Around line 126-132: Replace the try/except pattern used when adding migration
columns in loop_intelligence.py with contextlib.suppress to cleanly ignore
sqlite3.OperationalError; import contextlib (or directly from contextlib import
suppress) at the top of the module, and wrap the ALTER TABLE call in "with
suppress(sqlite3.OperationalError): conn.execute(...)" for the two nested loops
over ("activity_log","prep_outcomes") and ("session","timestamp") so the
migration logic remains the same but uses contextlib.suppress instead of an
empty except block.
- Around line 192-220: In log_prep, change the Optional type hints to PEP 604
unions and use the shared UTC alias: update the parameters from session:
Optional[int] and date: Optional[str] to session: int | None and date: str |
None, and replace timezone.utc uses (e.g., datetime.now(timezone.utc)) with the
project UTC alias (datetime.UTC) so the timestamp/date lines use datetime.UTC
consistently; keep function name log_prep, parameter names session and date, and
the datetime.now calls intact.
- Around line 536-581: The type hint for the session parameter in
update_patterns_file should use the modern union syntax; replace "session:
Optional[int] = None" with "session: int | None = None" in the
update_patterns_file signature so the hint reads int | None (no other code
changes needed, locate the parameter on the update_patterns_file function
definition).
- Around line 326-385: Replace use of timezone.utc with the newer datetime.UTC
constant: in get_activity_stats change the cutoff computation from
datetime.now(timezone.utc) to datetime.now(datetime.UTC); also update imports to
remove timezone if it becomes unused (ensure datetime is the module/class used
so datetime.UTC is in scope).
- Around line 280-323: In detect_manual change the date parameter type hint from
Optional[str] to the modern union form (date: str | None = None) and replace
datetime.now(timezone.utc).strftime(...) with
datetime.now(datetime.UTC).strftime(...) so it uses the datetime.UTC constant;
update any imports if necessary to preserve datetime name usage in the
detect_manual function and ensure type/usage matches the Ruff suggestions.
- Around line 17-26: The import block in loop_intelligence.py is unsorted and
missing the contextlib import; reorder and group the imports per Ruff (from
__future__ first, then standard library imports sorted alphabetically:
contextlib, datetime, json, pathlib.Path, sqlite3, collections.defaultdict,
typing.Any/Optional), followed by local imports, and add "import contextlib" so
contextlib.suppress is available; update the import statements around the
existing symbols (e.g., contextlib, json, sqlite3, defaultdict, datetime,
timedelta, timezone, Path, Any, Optional, and _emit_event_fn) to be properly
sorted and include the missing module.
- Around line 135-189: Update log_activity: change Optional[int]/Optional[str]
hints to union types (use int | None and str | None for session and date),
replace timezone.utc with datetime.UTC for timestamp/date generation, and add an
optional ctx: BrainContext | None = None parameter to match DB-access patterns;
keep using _get_db and _init_tables unchanged but accept ctx to align with SDK
conventions. For the emit block that calls _emit_event_fn, replace the bare
try/except with contextlib.suppress(Exception) to satisfy Ruff (or keep the
explicit try/except if you prefer but annotate why), and ensure _emit_event_fn
is called with the new ctx if it accepts context. Ensure imports reflect
datetime.UTC and contextlib.suppress and update the function signature and all
internal references accordingly.
- Around line 223-277: Change the date parameter annotation in log_outcome from
Optional[str] to str | None, and replace uses of timezone.utc with datetime.UTC
(update imports so the datetime module is imported as a module rather than
importing timezone/class directly) so the calls become
datetime.datetime.now(datetime.UTC).strftime(...) and
datetime.datetime.now(datetime.UTC).isoformat() in the log_outcome function and
its insert branch; keep all other behavior the same and ensure references to
datetime.strptime remain valid.
- Around line 392-437: The function signature and error handling in
query_tagged_interactions need fixing: change the session type hint from
Optional[int] to int | None (keep default None) and replace the bare "except
Exception: return []" with catching the exception and logging it (e.g., using
logging.exception or the module's logger) before returning the empty list so
errors aren't silently swallowed; update imports if necessary to include
logging.
In `@src/gradata/enhancements/scoring/memory_extraction.py`:
- Line 6: Replace the informal "Stolen from: Mem0's two-phase
extract-then-update pipeline." comment in memory_extraction.py with neutral
provenance text such as "Adapted from Mem0's two-phase extract-then-update
pipeline (source: <repo URL>, license: <license name>)", and update the two
other occurrences around lines 185-186 similarly; also add a NOTICE or
ATTRIBUTION entry documenting the source URL and license and confirm
compatibility with our Apache relicensing in the project attribution docs;
search for the string "Stolen from" to ensure all instances are replaced and
reference the module name memory_extraction.py when updating comments.
- Around line 41-50: The ExtractedFact dataclass allows out-of-range confidence
values; add a __post_init__ on ExtractedFact that validates confidence is >= 0.0
and <= 1.0 and raises a ValueError (with a clear message including the invalid
value) if not; locate the class definition for ExtractedFact and implement this
check so all constructed instances enforce the [0.0, 1.0] invariant used by
downstream scoring.
- Line 113: Replace the deprecated datetime.timezone.utc usage by importing and
using zoneinfo.UTC (add "from zoneinfo import UTC" and change
datetime.now(timezone.utc).isoformat() to datetime.now(UTC).isoformat()), and
remove the unnecessary f-string prefix on the literal at the other occurrence
(drop the leading "f" from the string that currently has no placeholders) so the
code no longer triggers Ruff UP017 and F541.
- Around line 268-279: The _find_similar() loop currently compares lexical
overlap between candidate_words and facts in existing without checking fact
type, allowing cross-type matches; fix this by gating comparisons on fact type
before computing overlap: retrieve the candidate's fact type (e.g.,
candidate_fact_type) and each fact's fact_type = fact.get("fact_type") and if
they differ, continue the loop, otherwise proceed to compute overlap and update
best_overlap/best_match (variables: existing, fact, candidate_words,
best_overlap, best_match) so only same-type facts are considered for
reconciliation.
In `@src/gradata/enhancements/scoring/reports.py`:
- Around line 123-130: The code hardcodes lessons_path relative to db.parent
(brain_dir/".claude/lessons.md"), which breaks non-standard workspace layouts;
change the function that currently uses brain_dir, lessons_path, lessons_count
and rules_count to accept a BrainContext (or otherwise obtain the configured
brain/lessons path from the provided context/config) and resolve the lessons
file via that context instead of db.parent / ".claude" / "lessons.md"; ensure
you add "from __future__ import annotations" if missing for type-safety, remove
any print()s, and use the context-provided path when checking exists(), reading
text(), and computing lessons_count/rules_count so brains stored elsewhere are
supported.
- Around line 97-107: The current query used when computing fda/unedited
inspects OUTPUT.data_json for a major_edit flag (thus counting nearly all
outputs as "unedited"); instead change the SQL executed by conn.execute (the
block that sets unedited used to compute first-draft acceptance fda) to count
OUTPUT events that do NOT have a later CORRECTION event with data_json
containing '"major_edit": true' — i.e., replace the current WHERE check on the
OUTPUT row with a correlated NOT EXISTS subquery (or an appropriate JOIN) that
looks for a CORRECTION row linked to that output (by output id, parent id, or
timestamp/session correlation) where type='CORRECTION' AND data_json LIKE
'%"major_edit": true%' and the correction occurs after the output; update the
SQL in the conn.execute call that assigns unedited so fda = round(unedited /
outputs, 4) reflects outputs without subsequent major_edit corrections.
In `@src/gradata/enhancements/scoring/success_conditions.py`:
- Around line 236-251: The try/except around importing and calling
compute_metrics currently swallows all errors; replace the bare "except
Exception: pass" with targeted error handling that logs failures and exception
details so issues aren't silent. Import or retrieve a logger (e.g., via the
logging module), then catch ImportError and AttributeError for the dynamic
import and a broad "except Exception as e" for runtime failures when calling
compute_metrics, and call logger.exception or logger.error including the
function name (compute_metrics), the variables blandness/bland_ok, and the
exception message before continuing; keep building and appending the
ConditionResult only when compute_metrics succeeds.
In `@src/gradata/enhancements/self_improvement.py`:
- Around line 1314-1329: The function get_maturity_phase currently treats
negative total_sessions as "INFANT"; add explicit validation at the start of
get_maturity_phase to detect negative values and raise a ValueError (or custom
exception used project-wide) with a clear message like "total_sessions must be
non-negative" to fail fast and prevent invalid state propagation; update
callers/tests if any expect negative handling.
In `@tests/test_agent_graduation.py`:
- Around line 150-158: The current pytest.mark.xfail on the agent graduation
test is masking a real confidence-update bug; either fix the rejection-path math
in the self_improvement code that updates confidence (so the test can pass and
you can remove the xfail), or if you cannot fix immediately, update the xfail
marker on the test (the pytest.mark.xfail block in
tests/test_agent_graduation.py) to reference a tracked issue ID and a clear
removal milestone (e.g. "issue: #<ID>, remove-by: v0.7") instead of the vague
note—ensure strict=True remains and the reason text includes the issue link and
target release so the test won't silently ship untracked.
In `@tests/test_cloud_sync.py`:
- Around line 152-156: In test_payload_has_sent_at_timestamp, replace the loose
truthiness check of p.sent_at with explicit ISO timestamp validation: locate the
test function test_payload_has_sent_at_timestamp and the helper _payload(),
parse p.sent_at (e.g., using datetime.fromisoformat or a timezone-aware parser)
to assert it is a valid ISO8601 datetime, verify it contains a UTC offset or 'Z'
(or that its tzinfo is not None) and optionally assert the parsed value is
within a reasonable range of now to ensure it's recent rather than just
non-empty.
In `@tests/test_enhancements.py`:
- Line 1: The file contains a duplicate "import pytest" statement; remove the
redundant import so only a single "import pytest" remains (keep the top-level
import and delete the later duplicate). Locate the duplicate "pytest" import in
tests/test_enhancements.py (the second occurrence) and remove it to avoid lint
noise and import duplication.
🪄 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: 26aa32f2-4a10-4e13-a846-7eb759d3fbec
📒 Files selected for processing (49)
CHANGELOG.mdCONTRIBUTING.mdLICENSEREADME.mddocs/LICENSING.mddocs/RELEASE-v0.5.0-DRAFT.mddocs/cloud/overview.mddocs/contributing.mddocs/faq.mddocs/getting-started/claude-code-setup.mddocs/index.mdexamples/domain-profiles/call_profile.pyexamples/domain-profiles/sales_profile.pygradata-install/README.mdgradata-install/bin/gradata-install.jsgradata-install/package.jsonpyproject.tomlsrc/gradata/_core.pysrc/gradata/cloud/sync.pysrc/gradata/detection/addition_pattern.pysrc/gradata/detection/correction_conflict.pysrc/gradata/enhancements/bandits/__init__.pysrc/gradata/enhancements/bandits/collaborative_filter.pysrc/gradata/enhancements/bandits/contextual_bandit.pysrc/gradata/enhancements/graduation/__init__.pysrc/gradata/enhancements/graduation/agent_graduation.pysrc/gradata/enhancements/graduation/judgment_decay.pysrc/gradata/enhancements/graduation/rules_distillation.pysrc/gradata/enhancements/metrics.pysrc/gradata/enhancements/profiling/__init__.pysrc/gradata/enhancements/profiling/tone_profile.pysrc/gradata/enhancements/scoring/__init__.pysrc/gradata/enhancements/scoring/brain_scores.pysrc/gradata/enhancements/scoring/calibration.pysrc/gradata/enhancements/scoring/correction_tracking.pysrc/gradata/enhancements/scoring/failure_detectors.pysrc/gradata/enhancements/scoring/gate_calibration.pysrc/gradata/enhancements/scoring/loop_intelligence.pysrc/gradata/enhancements/scoring/memory_extraction.pysrc/gradata/enhancements/scoring/reports.pysrc/gradata/enhancements/scoring/success_conditions.pysrc/gradata/enhancements/self_improvement.pytests/test_agent_graduation.pytests/test_brain.pytests/test_cloud_sync.pytests/test_coverage_gaps.pytests/test_enhancements.pytests/test_spawn_extraction.pytests/test_spec_compliance.py
💤 Files with no reviewable changes (2)
- tests/test_brain.py
- tests/test_spec_compliance.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (2)
src/gradata/**/*.py
⚙️ CodeRabbit configuration file
src/gradata/**/*.py: This is the core SDK. Check for: type safety (from future import annotations required), no print()
statements (use logging), all functions accepting BrainContext where DB access occurs, no hardcoded paths. Severity
scoring must clamp to [0,1]. Confidence values must be in [0.0, 1.0].
Files:
src/gradata/enhancements/profiling/__init__.pysrc/gradata/enhancements/scoring/__init__.pysrc/gradata/enhancements/bandits/__init__.pysrc/gradata/enhancements/graduation/__init__.pysrc/gradata/detection/addition_pattern.pysrc/gradata/enhancements/self_improvement.pysrc/gradata/enhancements/metrics.pysrc/gradata/detection/correction_conflict.pysrc/gradata/_core.pysrc/gradata/enhancements/scoring/memory_extraction.pysrc/gradata/enhancements/graduation/judgment_decay.pysrc/gradata/enhancements/scoring/failure_detectors.pysrc/gradata/enhancements/graduation/rules_distillation.pysrc/gradata/enhancements/bandits/contextual_bandit.pysrc/gradata/enhancements/scoring/success_conditions.pysrc/gradata/enhancements/scoring/correction_tracking.pysrc/gradata/enhancements/bandits/collaborative_filter.pysrc/gradata/enhancements/scoring/brain_scores.pysrc/gradata/cloud/sync.pysrc/gradata/enhancements/scoring/reports.pysrc/gradata/enhancements/scoring/gate_calibration.pysrc/gradata/enhancements/scoring/calibration.pysrc/gradata/enhancements/profiling/tone_profile.pysrc/gradata/enhancements/scoring/loop_intelligence.pysrc/gradata/enhancements/graduation/agent_graduation.py
tests/**
⚙️ CodeRabbit configuration file
tests/**: Test files. Verify: no hardcoded paths, assertions check specific values not just truthiness,
parametrized tests preferred for boundary conditions, floating point comparisons use pytest.approx.
Files:
tests/test_enhancements.pytests/test_spawn_extraction.pytests/test_agent_graduation.pytests/test_cloud_sync.pytests/test_coverage_gaps.py
🪛 GitHub Actions: CI
src/gradata/enhancements/scoring/correction_tracking.py
[error] 454-454: pyright: Argument of type "Path | None" cannot be assigned to parameter "db_path" of type "Path" in function "compute_correction_profile" (reportArgumentType).
src/gradata/enhancements/scoring/brain_scores.py
[error] 238-238: pyright: "compute_brain_scores" is not a known attribute of module "gradata._events" (reportAttributeAccessIssue).
🪛 GitHub Actions: SDK CI
src/gradata/enhancements/scoring/memory_extraction.py
[error] 113-113: Ruff UP017: Use datetime.UTC alias
[error] 214-214: Ruff F541: f-string without any placeholders
src/gradata/enhancements/graduation/judgment_decay.py
[error] 32-32: Ruff I001: Import block is un-sorted or un-formatted
src/gradata/enhancements/scoring/correction_tracking.py
[error] 21-21: Ruff TC005: Found empty type-checking block
src/gradata/enhancements/bandits/collaborative_filter.py
[error] 37-37: Ruff F401: dataclasses.field imported but unused
[error] 64-64: Ruff UP037: Remove quotes from type annotation
[error] 125-125: Ruff B905: zip() without an explicit strict= parameter
src/gradata/enhancements/scoring/brain_scores.py
[error] 27-27: Ruff TC005: Found empty type-checking block
[error] 236-236: Ruff RUF100: Unused noqa directive (non-enabled: PLC0415)
src/gradata/enhancements/scoring/reports.py
[error] 146-146: Ruff UP017: Use datetime.UTC alias
src/gradata/enhancements/scoring/gate_calibration.py
[error] 34-34: Ruff F401: dataclasses.field imported but unused
src/gradata/enhancements/scoring/calibration.py
[error] 31-31: Ruff F401: math imported but unused
[error] 32-32: Ruff F401: dataclasses.field imported but unused
src/gradata/enhancements/profiling/tone_profile.py
[error] 30-30: Ruff I001: Import block is un-sorted or un-formatted
[error] 121-121: Ruff UP037: Remove quotes from type annotation
[error] 253-253: Ruff UP037: Remove quotes from type annotation
src/gradata/enhancements/scoring/loop_intelligence.py
[error] 17-17: Ruff I001: Import block is un-sorted or un-formatted
[error] 129-132: Ruff SIM105: Use contextlib.suppress(sqlite3.OperationalError) instead of try-except-pass
[error] 143-143: Ruff UP045: Use X | None for type annotations
[error] 144-144: Ruff UP045: Use X | None for type annotations
[error] 148-148: Ruff UP017: Use datetime.UTC alias
[error] 149-149: Ruff UP017: Use datetime.UTC alias
[error] 165-184: Ruff SIM105: Use contextlib.suppress(Exception) instead of try-except-pass
[error] 197-197: Ruff UP045: Use X | None for type annotations
[error] 198-198: Ruff UP045: Use X | None for type annotations
[error] 201-201: Ruff UP017: Use datetime.UTC alias
[error] 202-202: Ruff UP017: Use datetime.UTC alias
[error] 229-229: Ruff UP045: Use X | None for type annotations
[error] 232-232: Ruff UP017: Use datetime.UTC alias
[error] 269-269: Ruff UP017: Use datetime.UTC alias
[error] 285-285: Ruff UP045: Use X | None for type annotations
[error] 288-288: Ruff UP017: Use datetime.UTC alias
[error] 331-331: Ruff UP017: Use datetime.UTC alias
[error] 394-394: Ruff UP045: Use X | None for type annotations
[error] 443-443: Ruff UP045: Use X | None for type annotations
[error] 539-539: Ruff UP045: Use X | None for type annotations
src/gradata/enhancements/graduation/agent_graduation.py
[error] 46-46: Ruff I001: Import block is un-sorted or un-formatted
[error] 253-253: Ruff UP017: Use datetime.UTC alias
[error] 453-453: Ruff UP017: Use datetime.UTC alias
[error] 776-776: Ruff UP037: Remove quotes from type annotation
[error] 823-823: Ruff UP037: Remove quotes from type annotation
🪛 LanguageTool
docs/index.md
[grammar] ~12-~12: Use a hyphen to join words.
Context: ...r judgment. One brain, many hosts. Open source SDK (Apache-2.0), optional hosted...
(QB_NEW_EN_HYPHEN)
docs/LICENSING.md
[style] ~16-~16: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...obligations. No dual-license paperwork. No "commercial license" to buy. ## Gradat...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (27)
src/gradata/detection/correction_conflict.py (1)
1-2: LGTM!License header updated to Apache-2.0 as part of the relicensing effort. No functional changes in this file.
src/gradata/detection/addition_pattern.py (1)
1-2: LGTM!License header updated to Apache-2.0. The addition pattern detection logic remains unchanged and well-implemented with proper input validation and thread safety.
src/gradata/enhancements/graduation/__init__.py (1)
1-1: LGTM!Package initializer with descriptive docstring. No code requiring type annotations.
gradata-install/bin/gradata-install.js (1)
20-28: LGTM!Well-implemented deprecation notice that:
- Uses stderr appropriately for warnings
- Provides clear migration instructions (
pip install gradata && gradata hooks install)- Includes documentation link
- Preserves backward compatibility by keeping existing functionality
gradata-install/package.json (1)
3-4: LGTM!Package metadata properly updated for deprecation:
- Version aligned with SDK v0.6.0
- Deprecation signaled via description, keywords, and npm's
deprecatedfield- License updated to Apache-2.0 consistent with the repo-wide relicensing
Also applies to: 17-17, 20-21
src/gradata/enhancements/graduation/judgment_decay.py (1)
117-218: LGTM!The
compute_decayfunction is well-implemented:
- Pure function with no side effects as documented
- Confidence values properly bounded (floor at 0.10 via
max, ceiling at tier limits viamin)- Session-type filtering prevents inappropriate decay
- RULE tier immunity correctly handled
- Clear DecayResult outputs with actionable reasons
examples/domain-profiles/call_profile.py (2)
1-43: LGTM!Well-documented example module demonstrating behavioral pattern extraction from call transcripts. The module:
- Follows good practices with type annotations and clear docstrings
- Implements pure computation with no I/O dependencies
- Provides comprehensive feature extraction (questions, stories, objections, etc.)
435-478: LGTM!The
build_call_profilefunction properly:
- Aggregates outcomes with win/loss segmentation
- Computes confidence linearly clamped to [0.0, 1.0] via
min(1.0, total * 0.03)- Discovers patterns from meaningful deltas (>20% threshold)
examples/domain-profiles/sales_profile.py (1)
124-218: LGTM!The
computemethod is well-implemented:
- Minimum sample thresholds (≥3) prevent noisy rate calculations
- Compliance properly bounded with
max(0.0, ...)- Rates naturally bounded [0.0, 1.0] as fractions
- Graceful handling of invalid timestamps with silent skip
- Per-prospect grouping prevents cross-contamination in cadence analysis
docs/getting-started/claude-code-setup.md (1)
134-134: License text update is consistent and clear.The table now matches the Apache-2.0 licensing pivot and stays aligned with other docs.
docs/contributing.md (1)
114-114: Looks good.The contribution licensing statement is updated consistently with the new Apache-2.0 model.
src/gradata/_core.py (1)
1061-1061: SKILL metadata license update is correct.
license: Apache-2.0in exported content matches the v0.6.0 relicensing intent.CONTRIBUTING.md (1)
44-44: LGTM.Top-level contributing guide now correctly reflects Apache-2.0 contribution terms.
src/gradata/enhancements/scoring/gate_calibration.py (1)
64-205: LGTM!The
GateCalibratorimplementation is well-structured with proper edge case handling:
- Integer-based threshold sweep avoids float precision issues
- Division-by-zero guards in precision/recall/F1 calculations
- Configurable sweep range and tie-breaking behavior
src/gradata/enhancements/scoring/success_conditions.py (3)
58-78: LGTM!Clean helper function with appropriate
sqlite3.OperationalErrorhandling for schema compatibility.
93-135: LGTM!Well-structured entry point with proper edge case handling for missing DB and insufficient data scenarios.
265-283: LGTM!Clean report formatting with clear pass/fail indicators and actionable guidance.
src/gradata/enhancements/graduation/rules_distillation.py (2)
57-112: LGTM!Clean implementation of distillation candidate detection with proper grouping, filtering, and sorting logic. The 30% keyword overlap threshold for coverage detection is a reasonable heuristic for simple deduplication.
141-157: LGTM!Clean formatting function with proper empty-case handling.
src/gradata/enhancements/profiling/tone_profile.py (3)
126-214: LGTM!Comprehensive tone feature extraction with well-documented patterns for formality, greeting, CTA, and opener classification. The regex patterns are appropriately anchored and handle common edge cases.
264-358: LGTM!Clean profile building with proper confidence clamping (
min(1.0, total_samples * 0.03)) and EMA blending for incremental updates.
472-546: LGTM!Well-designed tiered prompt generation with confidence-based strength words (Consider/Use/Always). The thresholds (0.60, 0.90) align with the INSTINCT→PATTERN→RULE graduation tiers.
src/gradata/enhancements/graduation/agent_graduation.py (5)
84-126: LGTM!Well-structured
AgentProfiledataclass with proper computed properties for FDA and acceptance rates. Thematurity_phaseproperty delegates correctly to the shared graduation utility.
145-183: LGTM!Clean
DeterministicRuleimplementation with regex-based enforcement. Thecheckmethod properly handles the no-pattern case.
477-515: LGTM!Confidence updates are properly clamped with
min(1.0, ...)andmax(0.0, ...). The promotion logic correctly checks both confidence threshold and minimum application count before advancing lesson state.
517-548: LGTM!Gate graduation logic is well-structured with proper demotion handling (3 consecutive rejections) and clear promotion thresholds (70% FDA for PREVIEW, 90% FDA for AUTO).
690-774: LGTM!
compute_quality_scoresprovides a clean interface matching the legacyagent_quality_scores()shape, enabling drop-in replacement while using the richer graduation profile data.
Comment on lines
+50
to
+54
| - **2598 tests passing** (up from 2561). 37 previously cloud-gated tests | ||
| now run. 19 legitimate skips remain (external API smoke tests, proprietary | ||
| `meta_rules` flat module that lives only in the private cloud repo). | ||
| - 2 tests marked `@pytest.mark.xfail` for v0.7 reconciliation — API drift | ||
| between the cloud_backup snapshot and current SDK constants. |
There was a problem hiding this comment.
Coverage count appears stale in the 0.6.0 notes.
Line 50 reports 2,598 passing tests, while this PR’s release notes/objectives report 2,615. Please align the changelog number before tagging the release.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CHANGELOG.md` around lines 50 - 54, Update the stale test count in the 0.6.0
changelog entry: locate the string "**2598 tests passing**" in CHANGELOG.md and
change it to "**2615 tests passing**" (and scan the same 0.6.0 notes for any
other occurrences of 2598 to keep numbers consistent with the release
notes/objectives).
Comment on lines
+5
to
+7
| Yes, and with no strings attached. The SDK is released under **Apache-2.0** on [GitHub](https://github.com/Gradata/gradata). You can self-host it, fork it, extend it, ship it in commercial products, bundle it in your own SaaS, or keep your modifications private. No copyleft. No dual-license paperwork. | ||
|
|
||
| Gradata Cloud is a proprietary hosted service built on the SDK. It is optional. Nothing in the SDK depends on Cloud being reachable. | ||
| Gradata Cloud is a paid hosted service layered on top of the SDK. It is optional. Nothing in the SDK depends on Cloud being reachable — with BYOK you have the full product locally. |
There was a problem hiding this comment.
Cloud data-flow wording needs consistency with the actual sync privacy model.
This updated section states cloud is optional and local-first, but the same FAQ still claims raw correction text is sent by default when sync is enabled. That conflicts with src/gradata/cloud/sync.py (metrics-only telemetry by default, separate corpus opt-in). Please reconcile this page to a single privacy statement to avoid compliance/user-trust risk.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/faq.md` around lines 5 - 7, The FAQ wording contradicts the
implementation in src/gradata/cloud/sync.py: update docs/faq.md to state the
actual sync privacy model used by sync.py — telemetry is metrics-only by default
and raw correction/corpus data is only transmitted if the user explicitly opts
into corpus sync (corpus opt-in), and that Cloud remains
optional/locally-operable (BYOK). Reference the metrics-only default and corpus
opt-in behavior from src/gradata/cloud/sync.py in the text and remove any
blanket statement that raw correction text is sent by default when sync is
enabled.
| Gradata is procedural memory for AI agents. Every time you edit AI output, Gradata captures the correction, graduates it into a rule, and auto-generates a hook that enforces the rule on the next run. Your AI stops making the same mistake. It converges on your judgment. | ||
|
|
||
| One brain, many hosts. Open source SDK (AGPL-3.0), optional hosted cloud at [gradata.ai](https://gradata.ai). | ||
| One brain, many hosts. Open source SDK (Apache-2.0), optional hosted cloud at [gradata.ai](https://gradata.ai). |
There was a problem hiding this comment.
Hyphenate the compound adjective in the tagline.
Use “Open-source SDK” instead of “Open source SDK” for standard usage in this sentence.
🧰 Tools
🪛 LanguageTool
[grammar] ~12-~12: Use a hyphen to join words.
Context: ...r judgment. One brain, many hosts. Open source SDK (Apache-2.0), optional hosted...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/index.md` at line 12, In the tagline string "One brain, many hosts. Open
source SDK (Apache-2.0), optional hosted cloud at
[gradata.ai](https://gradata.ai)." replace the unhyphenated compound adjective
"Open source SDK" with the hyphenated form "Open-source SDK" so the sentence
reads "One brain, many hosts. Open-source SDK (Apache-2.0), optional hosted
cloud at [gradata.ai](https://gradata.ai)."
|
|
||
| AGPL-3.0-or-later. Full text in `LICENSE`. See `docs/LICENSING.md` for the | ||
| dual-license story (AGPL for community, commercial for closed-source use). | ||
| Apache-2.0. Full text in `LICENSE`. See `docs/LICENSING.md` — SDK is permissively open, hosted SaaS at gradata.ai is the paid tier. |
There was a problem hiding this comment.
v0.5 release note now states the wrong license.
Line 84 claims Apache-2.0 for v0.5, but v0.5 is explicitly AGPL in this release plan. This can cause legal/compliance confusion for users auditing historical versions.
Proposed fix
-Apache-2.0. Full text in `LICENSE`. See `docs/LICENSING.md` — SDK is permissively open, hosted SaaS at gradata.ai is the paid tier.
+AGPL-3.0-or-later for v0.5.0. (Apache-2.0 begins with v0.6.0.) Full text in `LICENSE` and `docs/LICENSING.md`.📝 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
| Apache-2.0. Full text in `LICENSE`. See `docs/LICENSING.md` — SDK is permissively open, hosted SaaS at gradata.ai is the paid tier. | |
| AGPL-3.0-or-later for v0.5.0. (Apache-2.0 begins with v0.6.0.) Full text in `LICENSE` and `docs/LICENSING.md`. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/RELEASE-v0.5.0-DRAFT.md` at line 84, The release note text currently
reads "Apache-2.0. Full text in `LICENSE`. See `docs/LICENSING.md` — SDK is
permissively open, hosted SaaS at gradata.ai is the paid tier." but v0.5 is
AGPL; update that sentence to state "AGPL-3.0" (or "AGPL-3.0-or-later" as your
policy requires) and ensure the reference to `LICENSE` and `docs/LICENSING.md`
accurately reflect the AGPL license for v0.5; search for the exact sentence in
the v0.5 release note and replace it so the release note, the `LICENSE`
reference, and any mention of the SDK/licensing in `docs/LICENSING.md`
consistently indicate AGPL for v0.5.
Comment on lines
7
to
+10
| version = "0.5.0" | ||
| description = "AI that learns your judgment. Corrections become behavioral rules that converge on your style." | ||
| readme = "README.md" | ||
| license = "AGPL-3.0-or-later" | ||
| license = "Apache-2.0" |
There was a problem hiding this comment.
Package metadata version is still 0.5.0 in a v0.6.0 release PR.
Line 7 still declares version = "0.5.0". Publishing with this file will produce incorrect artifact/version metadata for this release train.
Proposed fix
-version = "0.5.0"
+version = "0.6.0"📝 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
| version = "0.5.0" | |
| description = "AI that learns your judgment. Corrections become behavioral rules that converge on your style." | |
| readme = "README.md" | |
| license = "AGPL-3.0-or-later" | |
| license = "Apache-2.0" | |
| version = "0.6.0" | |
| description = "AI that learns your judgment. Corrections become behavioral rules that converge on your style." | |
| readme = "README.md" | |
| license = "Apache-2.0" |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pyproject.toml` around lines 7 - 10, The pyproject.toml still declares the
old version string; update the version metadata by changing the version =
"0.5.0" entry to the correct release version (e.g., version = "0.6.0") so
package artifacts and metadata match this release; locate the version field in
pyproject.toml (the version = "...") and update it accordingly before
publishing.
Comment on lines
+268
to
+279
| for fact in existing: | ||
| fact_words = set(fact.get("content", "").lower().split()) | ||
| if not fact_words: | ||
| continue | ||
|
|
||
| overlap = len(candidate_words & fact_words) | ||
| union = len(candidate_words | fact_words) | ||
| jaccard = overlap / union if union > 0 else 0 | ||
|
|
||
| if jaccard > 0.5 and jaccard > best_overlap: | ||
| best_overlap = jaccard | ||
| best_match = fact |
There was a problem hiding this comment.
Prevent cross-type matches during reconciliation.
_find_similar() matches only by lexical overlap. Without fact_type gating, a temporal fact can update/invalidate a preference (and vice versa) if wording overlaps.
🔧 Proposed fix
for fact in existing:
+ existing_type = fact.get("fact_type")
+ if existing_type and existing_type != candidate.fact_type:
+ continue
fact_words = set(fact.get("content", "").lower().split())
if not fact_words:
continue🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/scoring/memory_extraction.py` around lines 268 -
279, The _find_similar() loop currently compares lexical overlap between
candidate_words and facts in existing without checking fact type, allowing
cross-type matches; fix this by gating comparisons on fact type before computing
overlap: retrieve the candidate's fact type (e.g., candidate_fact_type) and each
fact's fact_type = fact.get("fact_type") and if they differ, continue the loop,
otherwise proceed to compute overlap and update best_overlap/best_match
(variables: existing, fact, candidate_words, best_overlap, best_match) so only
same-type facts are considered for reconciliation.
Comment on lines
+1314
to
+1329
| def get_maturity_phase(total_sessions: int) -> str: | ||
| """Determine brain maturity phase from total session count. | ||
|
|
||
| INFANT (<50): fresh brain, high correction rate expected | ||
| ADOLESCENT (<100): patterns forming, lessons graduating | ||
| MATURE (<200): stable rules, meta-rules emerging | ||
| STABLE (200+): compound learning, minimal new instincts | ||
| """ | ||
| if total_sessions < 50: | ||
| return "INFANT" | ||
| elif total_sessions < 100: | ||
| return "ADOLESCENT" | ||
| elif total_sessions < 200: | ||
| return "MATURE" | ||
| else: | ||
| return "STABLE" |
There was a problem hiding this comment.
Validate negative total_sessions explicitly.
At Line 1322, negative counts are treated as INFANT. This can mask bad session-state data and produce misleading maturity behavior. Reject invalid negatives at the helper boundary.
Proposed fix
def get_maturity_phase(total_sessions: int) -> str:
@@
- if total_sessions < 50:
+ if total_sessions < 0:
+ raise ValueError("total_sessions must be >= 0")
+ if total_sessions < 50:
return "INFANT"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/self_improvement.py` around lines 1314 - 1329, The
function get_maturity_phase currently treats negative total_sessions as
"INFANT"; add explicit validation at the start of get_maturity_phase to detect
negative values and raise a ValueError (or custom exception used project-wide)
with a clear message like "total_sessions must be non-negative" to fail fast and
prevent invalid state propagation; update callers/tests if any expect negative
handling.
Comment on lines
+150
to
+158
| @pytest.mark.xfail( | ||
| reason=( | ||
| "API drift from cloud_backup snapshot. Rejection path in SDK self_improvement.py " | ||
| "uses different sign conventions than backup — produces confidence INCREASE where " | ||
| "test expects decrease. Reconcile in v0.7: verify rejection-path semantics in " | ||
| "agent_graduation vs self_improvement." | ||
| ), | ||
| strict=True, | ||
| ) |
There was a problem hiding this comment.
This xfail currently masks a core confidence-update correctness bug.
The reason text explicitly states rejected outcomes can increase confidence. Keeping this under xfail lets a known behavioral defect ship silently. Prefer fixing the rejection-path math before release, or at minimum link a tracked issue and a removal milestone in the marker.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/test_agent_graduation.py` around lines 150 - 158, The current
pytest.mark.xfail on the agent graduation test is masking a real
confidence-update bug; either fix the rejection-path math in the
self_improvement code that updates confidence (so the test can pass and you can
remove the xfail), or if you cannot fix immediately, update the xfail marker on
the test (the pytest.mark.xfail block in tests/test_agent_graduation.py) to
reference a tracked issue ID and a clear removal milestone (e.g. "issue: #<ID>,
remove-by: v0.7") instead of the vague note—ensure strict=True remains and the
reason text includes the issue link and target release so the test won't
silently ship untracked.
Comment on lines
+152
to
+156
| def test_payload_has_sent_at_timestamp(self): | ||
| p = _payload() | ||
| assert p.sent_at # auto-populated | ||
| assert "T" in p.sent_at # ISO format | ||
|
|
There was a problem hiding this comment.
Use explicit timestamp validation instead of truthiness.
assert p.sent_at is too weak; parse and validate the timestamp shape/timezone explicitly.
Proposed fix
+from datetime import datetime
@@
def test_payload_has_sent_at_timestamp(self):
p = _payload()
- assert p.sent_at # auto-populated
- assert "T" in p.sent_at # ISO format
+ parsed = datetime.fromisoformat(p.sent_at)
+ assert parsed.tzinfo is not NoneAs per coding guidelines, tests/**: “assertions check specific values not just truthiness.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/test_cloud_sync.py` around lines 152 - 156, In
test_payload_has_sent_at_timestamp, replace the loose truthiness check of
p.sent_at with explicit ISO timestamp validation: locate the test function
test_payload_has_sent_at_timestamp and the helper _payload(), parse p.sent_at
(e.g., using datetime.fromisoformat or a timezone-aware parser) to assert it is
a valid ISO8601 datetime, verify it contains a UTC offset or 'Z' (or that its
tzinfo is not None) and optionally assert the parsed value is within a
reasonable range of now to ensure it's recent rather than just non-empty.
| @@ -1,4 +1,4 @@ | |||
| import pytest; pytest.importorskip('gradata.enhancements.self_improvement', reason='requires gradata_cloud') | |||
| import pytest | |||
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify duplicate pytest imports in this file.
rg -n '^import pytest$' tests/test_enhancements.py
# Expected: currently two matches (Line 1 and Line 30); after fix, one match.Repository: Gradata/gradata
Length of output: 91
Remove duplicate pytest import at line 1.
The file imports pytest at both line 1 and line 30. Keep only one import to avoid lint noise.
Suggested fix
-import pytest
"""
Enhancement module tests for the Gradata.📝 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
| import pytest | |
| """ | |
| Enhancement module tests for the Gradata. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/test_enhancements.py` at line 1, The file contains a duplicate "import
pytest" statement; remove the redundant import so only a single "import pytest"
remains (keep the top-level import and delete the later duplicate). Locate the
duplicate "pytest" import in tests/test_enhancements.py (the second occurrence)
and remove it to avoid lint noise and import duplication.
Comment on lines
+192
to
+201
| def load_arms(self, data: list[dict]) -> None: | ||
| """Load arm data from DB.""" | ||
| for d in data: | ||
| arm = RuleArm( | ||
| rule_id=d["rule_id"], | ||
| alpha=d.get("alpha", 1.0), | ||
| beta=d.get("beta", 1.0), | ||
| total_pulls=d.get("total_pulls", 0), | ||
| context_scores=d.get("context_scores", {}), | ||
| ) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
fd "contextual_bandit.py" --type fRepository: Gradata/gradata
Length of output: 112
🏁 Script executed:
wc -l src/gradata/enhancements/bandits/contextual_bandit.pyRepository: Gradata/gradata
Length of output: 116
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | head -50Repository: Gradata/gradata
Length of output: 2129
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | sed -n '1,40p'Repository: Gradata/gradata
Length of output: 1730
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | sed -n '192,220p'Repository: Gradata/gradata
Length of output: 564
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | sed -n '80,150p'Repository: Gradata/gradata
Length of output: 3135
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | sed -n '44,78p'Repository: Gradata/gradata
Length of output: 1533
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | sed -n '50,75p'Repository: Gradata/gradata
Length of output: 1151
🏁 Script executed:
cat -n src/gradata/enhancements/bandits/contextual_bandit.py | sed -n '55,72p'Repository: Gradata/gradata
Length of output: 827
Add validation in load_arms() to clamp or reject invalid parameter values.
load_arms() accepts alpha, beta, and context_scores from persisted data without validation. Since sample() calls random.betavariate(self.alpha, self.beta), any stored value where alpha <= 0 or beta <= 0 will crash at runtime. Additionally, context_scores values are blended into final scores (line 141–142) and must remain in [0.0, 1.0] per coding guidelines. Validate or reject invalid state on ingest.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/bandits/contextual_bandit.py` around lines 192 -
201, The load_arms method currently trusts persisted values for alpha, beta, and
context_scores which can break sampling and scoring; update load_arms to
validate the incoming values for RuleArm creation: ensure alpha and beta are > 0
(either clamp to a minimum like 1e-6 or raise a ValueError) and ensure every
context_scores value is within [0.0, 1.0] (either clamp or reject), and if you
choose to clamp, document defaults used; make these checks where RuleArm(...) is
constructed so sample() and the blending logic that uses context_scores are
safe.
Comment on lines
+46
to
+68
| from __future__ import annotations | ||
|
|
||
| import json | ||
| import re | ||
| from dataclasses import dataclass, field | ||
| from datetime import datetime, timezone | ||
| from pathlib import Path | ||
|
|
||
| # Import graduation constants from self_improvement (same research-backed values) | ||
| from gradata.enhancements.self_improvement import ( | ||
| SURVIVAL_BONUS, | ||
| ACCEPTANCE_BONUS, | ||
| MISFIRE_PENALTY, | ||
| PATTERN_THRESHOLD, | ||
| RULE_THRESHOLD, | ||
| MIN_APPLICATIONS_FOR_PATTERN, | ||
| MIN_APPLICATIONS_FOR_RULE, | ||
| LessonState, | ||
| Lesson, | ||
| parse_lessons, | ||
| format_lessons, | ||
| get_maturity_phase, | ||
| ) |
There was a problem hiding this comment.
Fix import block sorting per pipeline failure.
Ruff I001 indicates the import block is un-sorted or un-formatted.
from __future__ import annotations
import json
import re
from dataclasses import dataclass, field
-from datetime import datetime, timezone
+from datetime import UTC, datetime
from pathlib import Path
# Import graduation constants from self_improvement (same research-backed values)
from gradata.enhancements.self_improvement import (
- SURVIVAL_BONUS,
ACCEPTANCE_BONUS,
+ Lesson,
+ LessonState,
+ MIN_APPLICATIONS_FOR_PATTERN,
+ MIN_APPLICATIONS_FOR_RULE,
MISFIRE_PENALTY,
PATTERN_THRESHOLD,
RULE_THRESHOLD,
- MIN_APPLICATIONS_FOR_PATTERN,
- MIN_APPLICATIONS_FOR_RULE,
- LessonState,
- Lesson,
+ SURVIVAL_BONUS,
+ format_lessons,
+ get_maturity_phase,
parse_lessons,
- format_lessons,
- get_maturity_phase,
)🧰 Tools
🪛 GitHub Actions: SDK CI
[error] 46-46: Ruff I001: Import block is un-sorted or un-formatted
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/graduation/agent_graduation.py` around lines 46 -
68, The import block in agent_graduation.py is not sorted (Ruff I001); reorder
imports so they follow standard grouping and alphabetical order: keep "from
__future__ import annotations" first, then standard library imports (json, re,
dataclasses, datetime, pathlib) alphabetized, then a blank line, then the local
package import from gradata.enhancements.self_improvement with its symbols
(SURVIVAL_BONUS, ACCEPTANCE_BONUS, MISFIRE_PENALTY, PATTERN_THRESHOLD,
RULE_THRESHOLD, MIN_APPLICATIONS_FOR_PATTERN, MIN_APPLICATIONS_FOR_RULE,
LessonState, Lesson, parse_lessons, format_lessons, get_maturity_phase) sorted
alphabetically in the parentheses; run isort/ruff or manually apply this
ordering so the import block passes the linter.
Comment on lines
+252
to
+253
| def _now() -> str: | ||
| return datetime.now(timezone.utc).isoformat() |
There was a problem hiding this comment.
Use datetime.UTC alias instead of timezone.utc.
Python 3.11+ prefers the datetime.UTC alias.
def _now() -> str:
- return datetime.now(timezone.utc).isoformat()
+ return datetime.now(UTC).isoformat()🧰 Tools
🪛 GitHub Actions: SDK CI
[error] 253-253: Ruff UP017: Use datetime.UTC alias
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/graduation/agent_graduation.py` around lines 252 -
253, The _now function should use the new datetime.UTC alias instead of
timezone.utc; update the call in _now() to
datetime.now(datetime.UTC).isoformat() and adjust imports if necessary (remove
or stop using timezone) so the function uses datetime.UTC consistently;
reference: function _now in agent_graduation.py.
| category = "AGENT_" + profile.agent_type.upper() | ||
| if edit_category: | ||
| category = edit_category.upper() | ||
| today = datetime.now(timezone.utc).strftime("%Y-%m-%d") |
There was a problem hiding this comment.
Use datetime.UTC alias here as well.
- today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+ today = datetime.now(UTC).strftime("%Y-%m-%d")📝 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
| today = datetime.now(timezone.utc).strftime("%Y-%m-%d") | |
| today = datetime.now(UTC).strftime("%Y-%m-%d") |
🧰 Tools
🪛 GitHub Actions: SDK CI
[error] 453-453: Ruff UP017: Use datetime.UTC alias
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/graduation/agent_graduation.py` at line 453, Replace
the explicit timezone.utc usage when generating today's date: in the call to
datetime.now (the expression datetime.now(timezone.utc).strftime("%Y-%m-%d")),
use the datetime.UTC alias instead (i.e.,
datetime.now(datetime.UTC).strftime(...)) so the code uses the standardized UTC
alias; update any import if needed to reference datetime.UTC alongside the
existing datetime.now usage.
| "best_agent": best, | ||
| } | ||
|
|
||
| def get_deterministic_rules(self, agent_type: str, task_type: str = "") -> list["DeterministicRule"]: |
There was a problem hiding this comment.
Remove quotes from type annotation.
With from __future__ import annotations, forward reference quotes are unnecessary.
- def get_deterministic_rules(self, agent_type: str, task_type: str = "") -> list["DeterministicRule"]:
+ def get_deterministic_rules(self, agent_type: str, task_type: str = "") -> list[DeterministicRule]:📝 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
| def get_deterministic_rules(self, agent_type: str, task_type: str = "") -> list["DeterministicRule"]: | |
| def get_deterministic_rules(self, agent_type: str, task_type: str = "") -> list[DeterministicRule]: |
🧰 Tools
🪛 GitHub Actions: SDK CI
[error] 776-776: Ruff UP037: Remove quotes from type annotation
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/graduation/agent_graduation.py` at line 776, The
return type on get_deterministic_rules uses a quoted forward reference
"DeterministicRule"; remove the quotes and use a native typed annotation
list[DeterministicRule] instead (i.e., change def get_deterministic_rules(... )
-> list["DeterministicRule"] to -> list[DeterministicRule]) so it relies on from
__future__ import annotations; update only the annotation on the
get_deterministic_rules function signature.
Comment on lines
+23
to
+26
| from dataclasses import dataclass, field | ||
| from typing import Any | ||
|
|
||
| from gradata.enhancements.metrics import MetricsWindow |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and read the imports section (lines 1-30)
fd -t f 'failure_detectors.py' src/gradataRepository: Gradata/gradata
Length of output: 112
🏁 Script executed:
# Read the file to verify import state and check both issues
cat -n src/gradata/enhancements/scoring/failure_detectors.py | head -40Repository: Gradata/gradata
Length of output: 1821
🏁 Script executed:
# Check lines 203-245 to verify the hardcoded threshold issue
cat -n src/gradata/enhancements/scoring/failure_detectors.py | sed -n '200,250p'Repository: Gradata/gradata
Length of output: 2202
🏁 Script executed:
# Check other files in src/gradata/ to verify the pattern of using future-annotations
rg "from __future__ import annotations" src/gradata --type py -l | head -10Repository: Gradata/gradata
Length of output: 488
Add the required future-annotations import and use configurable thresholds in alert messages.
This core SDK module is missing from __future__ import annotations (required for src/gradata/**/*.py), and the detect_regression_to_mean() function hardcodes the threshold value 0.70 in both the evidence dict (line 229) and alert message (line 243) instead of using the configurable blandness_warn parameter. The hardcoded values mislead callers when they override the defaults.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/scoring/failure_detectors.py` around lines 23 - 26,
Add the missing future annotations import by adding "from __future__ import
annotations" at the top of the module, and update detect_regression_to_mean to
use the blandness_warn parameter (not the hardcoded 0.70) wherever the threshold
is reported: replace the literal 0.70 in the evidence dict and in the alert
message generation with the blandness_warn variable so the evidence["threshold"]
and the alert text reflect the configured value.
|
|
||
| from __future__ import annotations | ||
|
|
||
| from dataclasses import dataclass, field |
There was a problem hiding this comment.
Remove unused import field.
Pipeline failure indicates field is imported but never used.
-from dataclasses import dataclass, field
+from dataclasses import dataclass🧰 Tools
🪛 GitHub Actions: SDK CI
[error] 34-34: Ruff F401: dataclasses.field imported but unused
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/scoring/gate_calibration.py` at line 34, The import
statement currently brings in an unused symbol `field` from dataclasses (see the
line importing "dataclass, field"); remove `field` from the import so it reads
only `from dataclasses import dataclass` to eliminate the unused import warning
and pipeline failure.
Comment on lines
+97
to
+107
| # First-draft acceptance (domain-agnostic: checks major_edit flag, not user name) | ||
| fda = 0.0 | ||
| if outputs > 0: | ||
| try: | ||
| # Count outputs where no CORRECTION followed with major_edit=true | ||
| unedited = conn.execute( | ||
| "SELECT COUNT(*) FROM events WHERE type='OUTPUT' " | ||
| "AND data_json NOT LIKE '%\"major_edit\": true%'" | ||
| ).fetchone()[0] | ||
| fda = round(unedited / outputs, 4) | ||
| except sqlite3.OperationalError: |
There was a problem hiding this comment.
first_draft_acceptance is computed from the wrong rows.
This query inspects OUTPUT.data_json for "major_edit": true, but the comment says you want to detect whether a later correction happened. As written, almost every output is counted as unedited unless OUTPUT events themselves embed that flag, so the metric is inflated and misleading.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/scoring/reports.py` around lines 97 - 107, The
current query used when computing fda/unedited inspects OUTPUT.data_json for a
major_edit flag (thus counting nearly all outputs as "unedited"); instead change
the SQL executed by conn.execute (the block that sets unedited used to compute
first-draft acceptance fda) to count OUTPUT events that do NOT have a later
CORRECTION event with data_json containing '"major_edit": true' — i.e., replace
the current WHERE check on the OUTPUT row with a correlated NOT EXISTS subquery
(or an appropriate JOIN) that looks for a CORRECTION row linked to that output
(by output id, parent id, or timestamp/session correlation) where
type='CORRECTION' AND data_json LIKE '%"major_edit": true%' and the correction
occurs after the output; update the SQL in the conn.execute call that assigns
unedited so fda = round(unedited / outputs, 4) reflects outputs without
subsequent major_edit corrections.
Comment on lines
+123
to
+130
| brain_dir = db.parent | ||
| lessons_path = brain_dir.parent / ".claude" / "lessons.md" | ||
| lessons_count = 0 | ||
| rules_count = 0 | ||
| if lessons_path.exists(): | ||
| text = lessons_path.read_text(encoding="utf-8") | ||
| lessons_count = text.count("[INSTINCT") + text.count("[PATTERN") | ||
| rules_count = text.count("[RULE") |
There was a problem hiding this comment.
Avoid hardcoding .claude/lessons.md relative to db.parent.
This assumes a single workspace layout and breaks brains stored elsewhere. Resolve the lessons file from configuration/context instead of stitching a fixed path here. As per coding guidelines, src/gradata/**/*.py: This is the core SDK. Check for: type safety (from future import annotations required), no print() statements (use logging), all functions accepting BrainContext where DB access occurs, no hardcoded paths.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/scoring/reports.py` around lines 123 - 130, The code
hardcodes lessons_path relative to db.parent (brain_dir/".claude/lessons.md"),
which breaks non-standard workspace layouts; change the function that currently
uses brain_dir, lessons_path, lessons_count and rules_count to accept a
BrainContext (or otherwise obtain the configured brain/lessons path from the
provided context/config) and resolve the lessons file via that context instead
of db.parent / ".claude" / "lessons.md"; ensure you add "from __future__ import
annotations" if missing for type-safety, remove any print()s, and use the
context-provided path when checking exists(), reading text(), and computing
lessons_count/rules_count so brains stored elsewhere are supported.
Comment on lines
+236
to
+251
| # 6. Output not becoming bland (from metrics module) | ||
| try: | ||
| from gradata.enhancements.metrics import compute_metrics | ||
| m = compute_metrics(db_path, window) | ||
| blandness = m.get("blandness_score", 0.0) if isinstance(m, dict) else getattr(m, "blandness_score", 0.0) | ||
| bland_ok = blandness < 0.70 | ||
| conditions.append(ConditionResult( | ||
| name="output_not_bland", | ||
| met=bland_ok, | ||
| current_value=round(blandness, 4), | ||
| baseline_value=0.70, | ||
| trend="varied" if bland_ok else "generic", | ||
| detail=f"Blandness: {blandness:.2f} (threshold: 0.70)", | ||
| )) | ||
| except Exception: | ||
| pass |
There was a problem hiding this comment.
Bare except Exception: pass silently swallows errors.
This exception handler catches and discards all exceptions including ImportError, AttributeError, and unexpected runtime errors from compute_metrics. This makes debugging difficult when the blandness check fails silently.
Consider catching specific exceptions or at minimum logging the failure:
# 6. Output not becoming bland (from metrics module)
try:
from gradata.enhancements.metrics import compute_metrics
m = compute_metrics(db_path, window)
blandness = m.get("blandness_score", 0.0) if isinstance(m, dict) else getattr(m, "blandness_score", 0.0)
bland_ok = blandness < 0.70
conditions.append(ConditionResult(
name="output_not_bland",
met=bland_ok,
current_value=round(blandness, 4),
baseline_value=0.70,
trend="varied" if bland_ok else "generic",
detail=f"Blandness: {blandness:.2f} (threshold: 0.70)",
))
- except Exception:
- pass
+ except (ImportError, AttributeError, sqlite3.OperationalError):
+ pass # Blandness check unavailable or metrics module not configured🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/gradata/enhancements/scoring/success_conditions.py` around lines 236 -
251, The try/except around importing and calling compute_metrics currently
swallows all errors; replace the bare "except Exception: pass" with targeted
error handling that logs failures and exception details so issues aren't silent.
Import or retrieve a logger (e.g., via the logging module), then catch
ImportError and AttributeError for the dynamic import and a broad "except
Exception as e" for runtime failures when calling compute_metrics, and call
logger.exception or logger.error including the function name (compute_metrics),
the variables blandness/bland_ok, and the exception message before continuing;
keep building and appending the ConditionResult only when compute_metrics
succeeds.
6 tasks
This was referenced Apr 21, 2026
This was referenced Apr 30, 2026
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
Strategic pivot: the moat is the hosted service, not the algorithm code. Gradata now open-sources everything and charges for the cloud tier.
Breaking
gradata-installnpm package deprecated. Consolidate topip install gradata && gradata hooks install.Added
gradata_cloud_backup:enhancements/graduation/— agent_graduation, judgment_decay, rules_distillationenhancements/scoring/— brain_scores, calibration, correction_tracking, failure_detectors, gate_calibration, loop_intelligence, memory_extraction, reports, success_conditionsenhancements/bandits/— contextual_bandit, collaborative_filterenhancements/profiling/— tone_profileexamples/domain-profiles/— call_profile, sales_profile (recipes, not SDK primitives)gradata.cloud.sync) with 17 tests — transmits aggregated metrics (NOT correction content) to dashboard whencloud.sync = true. Separate opt-in for corpus contribution.get_maturity_phase()+format_metrics()helpers.Changed
pip install gradata), cleaner license section.MetricsWindow.avg_edit_distance→edit_distance_avg(internal API cleanup).Coverage
meta_rulesflat module).Commits (11)
chore(license): AGPL → Apache relicensefeat(sdk): merge 17 cloud algorithm filestest: un-skip 5 cloud-gated testsdocs: rewrite AGPL refs across 10 docschore(npm): deprecate gradata-installfeat(cloud): opt-in SDK cloud sync client + 17 testsdocs(changelog): v0.6.0 release notesdocs(readme): align license sectionWork discipline
Test plan
Generated with Gradata