Metadata-Version: 2.4
Name: gradata
Version: 0.4.0
Summary: AI that learns your judgment. Corrections become behavioral rules that converge on your style.
Project-URL: Homepage, https://github.com/gradata-systems/gradata
Project-URL: Documentation, https://github.com/gradata-systems/gradata#readme
Author-email: Gradata <oliver@gradata.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agents,ai,behavioral,corrections,judgment,learning,personalization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: cryptography>=41.0; extra == 'all'
Requires-Dist: google-genai>=1.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.0.0; extra == 'all'
Provides-Extra: cloud
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.0.0; extra == 'embeddings'
Provides-Extra: encrypted
Requires-Dist: cryptography>=41.0; extra == 'encrypted'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
Description-Content-Type: text/markdown

# Gradata — AI that learns your judgment

[![Tests](https://github.com/Gradata/gradata/actions/workflows/test.yml/badge.svg)](https://github.com/Gradata/gradata/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/gradata)](https://pypi.org/project/gradata/)
[![Python](https://img.shields.io/pypi/pyversions/gradata)](https://pypi.org/project/gradata/)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

Every correction you make teaches your AI something. Gradata captures those corrections, extracts the behavioral instruction behind them, and graduates it into a rule. Over time, your AI stops needing corrections. It converges on your judgment.

Not generally more intelligent. Calibrated to you.

```bash
pip install gradata
```

Works with any LLM. Python 3.11+. Zero required dependencies.

## Quick Start

```python
from gradata import Brain

brain = Brain.init("./my-brain")

# Your AI produces output. You fix it. Brain learns.
brain.correct(
    draft="We are pleased to inform you of our new product offering.",
    final="Hey, check out what we just shipped."
)
# Brain extracts: "Write in a casual, direct tone — avoid formal business language"

# Next session — inject learned rules into the prompt:
rules = brain.apply_brain_rules("write an email")
# > "[RULE:0.92] TONE: Write in a casual, direct tone..."

# Prove the brain is converging:
manifest = brain.manifest()
```

## How It Works

```
You correct your AI
       |
brain.correct(draft, final)
       |
Behavioral instruction extracted:
  "We are pleased..." → "Hey, check this out"
  = "Write in a casual, direct tone"
       |
Confidence grows with reinforcement:
  INSTINCT (0.40) → PATTERN (0.60) → RULE (0.90)
       |
3+ related rules → META-RULE emerges
  "Use casual tone" + "No sign-offs" + "Short sentences"
  = "Match Oliver's direct communication style"
       |
Your AI converges on YOUR judgment
```

## Why This Works

**Corrections are signal.** Every time you edit an AI's output, you're encoding your expertise. Most systems throw that signal away. Gradata captures it, extracts what you meant, and turns it into a rule.

**Meta-rules are personalized intelligence.** When individual rules start clustering — your email tone preferences aligning with your code review style aligning with your process preferences — meta-rules emerge. The AI starts predicting your patterns across domains. To you, it just "gets it." That's not general intelligence. That's convergence on your judgment.

**Convergence is measurable.** Track corrections-per-session over time. When the curve flattens, the brain has learned your style. That curve is the product demo.

## Ablation Experiment Results

We ran a controlled experiment: 10 tasks scored with and without brain rules.

| Metric | Without Rules | With Rules | Delta |
|--------|--------------|------------|-------|
| Overall quality | 6.60 | 7.47 | **+13.2%** |
| Preference adherence | 5.40 | 6.90 | **+1.50** |
| Correctness | 7.50 | 7.80 | +0.30 |

The rules didn't make the AI generally smarter. They made it smarter **for that specific user** — matching their email style, prospecting workflow, code conventions, and session handoff format.

## Behavioral Extraction

Old approach (diff fingerprints — useless):
> `"Content change (added: getattr)"`

New approach (behavioral instructions — rentable):
> `"Use getattr() for safe attribute access on objects that may lack the attribute"`

Every correction now produces an actionable instruction through:
1. **Cache hit** — instant lookup of previously extracted instructions
2. **Template match** — pre-built instructions for common patterns
3. **LLM extraction** — Haiku call for novel corrections (~$0.001 each)

## What Makes This Different

Memory systems remember what you said. Gradata learns how you think.

| System | Remembers | Learns from corrections | Graduates rules | Proves convergence |
|--------|-----------|------------------------|-----------------|-------------------|
| Mem0 | Yes | No | No | No |
| Letta (MemGPT) | Yes | No | No | No |
| LangChain Memory | Yes | No | No | No |
| **Gradata** | Yes | **Yes** | **Yes** | **Yes** |

**vs Mem0:** Mem0 stores context. Gradata evolves behavior. You could use both.

**vs fine-tuning:** Fine-tuning is expensive, slow, and loses the original model. Gradata adapts at inference time — every correction takes effect immediately.

**vs system prompts:** System prompts are static. Gradata's rules are dynamic — they graduate, decay, and evolve based on your corrections.

## Features

**Core learning loop:**
- `brain.correct(draft, final)` — captures corrections, extracts behavioral instructions, creates lessons
- `brain.apply_brain_rules(task)` — injects graduated rules into prompts
- `brain.manifest()` — mathematical proof the brain is converging
- `brain.prove()` — paired t-test showing correction rate decreased after graduation

**Event Bus (v0.3.0):**
- `brain.bus.on(event, handler)` — subscribe to any event in the pipeline
- Events: `correction.created`, `lesson.graduated`, `meta_rule.created`, `session.ended`

**Human-in-the-loop:**
- `brain.review_pending()` — list lessons awaiting approval
- `brain.approve_lesson(id)` / `brain.reject_lesson(id)` — pre-graduation veto
- `gradata review` CLI — approve/reject from terminal

**Integrations:**
- OpenAI, Anthropic, LangChain, CrewAI adapters
- MCP server for Claude Code, Cursor, Windsurf
- `gradata init --mcp` generates config automatically

## Status

Gradata is in active development (v0.4.0). The SDK is fully functional and free. Cloud features (dashboard, optimization, brain rental) are on the roadmap.

[Star the repo](https://github.com/Gradata/gradata) to follow progress.

## CLI

```bash
gradata init                          # Create a brain
gradata correct --draft "..." --final "..."  # Log a correction
gradata review                        # Approve/reject pending lessons
gradata stats                         # Brain health + convergence
gradata manifest --json               # Quality proof
gradata doctor                        # Diagnose issues
```

## Architecture

```
src/gradata/
  brain.py              # Brain class (public API)
  events_bus.py         # Central event bus
  _core.py              # Correction pipeline + behavioral extraction
  _events.py            # Append-only event log (JSONL + SQLite)
  enhancements/
    edit_classifier.py    # Classification + behavioral instruction extraction
    instruction_cache.py  # LLM extraction cache
    self_improvement.py   # Graduation pipeline
    diff_engine.py        # Edit distance, severity
    meta_rules.py         # Meta-rule synthesis
  rules/
    rule_engine.py        # Inject rules into prompts
    rule_ranker.py        # Context-aware ranking
  integrations/           # OpenAI, Anthropic, LangChain, CrewAI
  contrib/patterns/       # Optional agentic patterns
```

## Community

- [GitHub Issues](https://github.com/Gradata/gradata/issues) — bugs, features, questions
- [GitHub Discussions](https://github.com/Gradata/gradata/discussions) — ideas, show & tell

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

AGPL-3.0. Commercial license available.
