Metadata-Version: 2.1
Name: personal-evotaste
Version: 0.2.0
Summary: Developer personal-taste memory & self-evolution engine for AI coding agents.
Author: xzfnn
License: MIT License
        
        Copyright (c) 2026 xzfnn and PersonalEvoTaste Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/xzfnn/PersonalEvoTaste
Project-URL: Issues, https://github.com/xzfnn/PersonalEvoTaste/issues
Project-URL: Documentation, https://github.com/xzfnn/PersonalEvoTaste#readme
Project-URL: Changelog, https://github.com/xzfnn/PersonalEvoTaste/blob/main/CHANGELOG.md
Keywords: ai,agents,memory,preferences,self-evolution,prompt-engineering
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.6; extra == "dev"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.7; extra == "semantic"

<div align="center">

# 🧬 PersonalEvoTaste

**Teach your AI coding agent *your* taste — and watch it evolve.**

[![CI](https://github.com/xzfnn/PersonalEvoTaste/actions/workflows/ci.yml/badge.svg)](https://github.com/xzfnn/PersonalEvoTaste/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/personal-evotaste.svg)](https://pypi.org/project/personal-evotaste/)
[![Python](https://img.shields.io/pypi/pyversions/personal-evotaste.svg)](https://pypi.org/project/personal-evotaste/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

</div>

---

## ✨ What is it?

LLM agents are great at writing *generic* code — but they have **zero memory of your personal preferences**:
indentation tastes, library choices, naming conventions, the brutalist UI you love, the verbose
docstrings you hate. Every new chat resets to zero.

**PersonalEvoTaste** is a small, dependency-light library that gives an AI agent a **persistent,
self-evolving memory of your taste**. Feed it the agent's output + your feedback, and it distils,
deduplicates, reinforces and decays rules over time — then re-injects the top ones into the next
prompt.

```
        ┌──────────────┐  feedback   ┌──────────────────┐  rules   ┌────────────┐
agent → │ your review  │ ──────────► │ PersonalEvoTaste │ ───────► │ next prompt│
        └──────────────┘             └──────────────────┘          └────────────┘
                                              ▲  decay/reinforce        │
                                              └─────────────────────────┘
```

## 🚀 Features

- **🧠 Typed memory** — Pydantic v2 models, JSON-schema-friendly, versioned on disk.
- **🔌 Pluggable storage** — YAML / JSON / SQLite out of the box; bring-your-own backend.
- **🔬 Pluggable extractors** — deterministic heuristic by default; plug an LLM with `CallableExtractor`.
- **♻️ Self-evolution** — automatic deduplication, reinforcement on repetition, time decay, undo and dry-run previews.
- **⚖️ Ranked injection** — top-N rules by weight, optionally filtered per project.
- **🧩 Editor integrations** — export rules to `.cursorrules`, `.windsurfrules`, `CLAUDE.md` and Copilot instructions.
- **🖥️ Zero-dep CLI** — `personal-evotaste evolve / inject / list / remove / reset / export`.
- **🧪 Tested & typed** — pytest suite, ruff, mypy, CI on Python 3.9 → 3.12.
- **💾 Crash-safe writes** — atomic file replacement, SQLite transactions.

## 📦 Installation

```bash
pip install personal-evotaste
# or from source
pip install -e ".[dev]"
```

## ⚡ Quickstart

```python
from personal_evotaste import PersonalEvoTaste

taste = PersonalEvoTaste(memory_path="my_taste.yaml")

# 1. Inject your evolving taste into any prompt
prompt = taste.inject_taste(
    "Generate a login page",
    context="brutalist minimal project",
)
# → send `prompt` to your LLM of choice

# 2. After reviewing the agent's output, teach it
taste.evolve(
    agent_output="A flashy gradient login page with neon buttons",
    user_feedback="Too loud. I want calmer, monochrome, brutalist typography.",
    project_name="acme-landing",
)

# 3. Next time, the rule is already in the prompt — and reinforced if you repeat yourself
print(taste.inject_taste("Generate a signup page"))
```

## 🖥️ CLI

```bash
# Add a rule from feedback
personal-evotaste evolve \
  --output "A flashy gradient login page" \
  --feedback "Too loud. Prefer calm monochrome brutalist typography." \
  --project acme-landing

# Inject taste into a prompt
personal-evotaste inject "Generate a signup page" --context "acme-landing"

# Inspect the memory
personal-evotaste list
personal-evotaste export > snapshot.json

# Preview a rule without changing memory
personal-evotaste evolve --dry-run --output "..." --feedback "Prefer descriptive names"

# Undo the most recent evolution
personal-evotaste undo

# Export rules into AI editor instruction files
personal-evotaste export-rules -f cursor -o .cursorrules
personal-evotaste export-rules -f windsurf -o .windsurfrules
personal-evotaste export-rules -f claude -o CLAUDE.md
personal-evotaste export-rules -f copilot -o .github/copilot-instructions.md
```

Memory backend is auto-selected from the file extension: `.yaml` / `.json` / `.sqlite3`.

## 🔌 Plugging an LLM extractor

```python
from personal_evotaste import PersonalEvoTaste, CallableExtractor

def summarise_with_llm(agent_output: str, feedback: str, project: str) -> str:
    # call OpenAI / Anthropic / a local model here and return one short rule
    ...

taste = PersonalEvoTaste(
    memory_path="my_taste.yaml",
    extractor=CallableExtractor(summarise_with_llm),
)
```

## 🧱 Architecture

```
personal_evotaste/
├── models.py        # Pydantic models: TasteRule, FeedbackEvent, TasteMemory
├── storage.py       # BaseStorage + YAML / JSON / SQLite backends (atomic writes)
├── extractors.py    # RuleExtractor strategies + similarity-based deduplication
├── core.py          # PersonalEvoTaste façade (evolve / inject / ranking / decay)
├── cli.py           # argparse-based CLI (zero extra deps)
├── exceptions.py    # Typed error hierarchy
└── logging_config.py
```

See [`docs/architecture.md`](docs/architecture.md) for the design rationale.
See [`docs/integrations.md`](docs/integrations.md) for Cursor, Windsurf, Claude and Copilot setup.

## 🤝 Contributing

PRs, issues and ideas are very welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and our
[Code of Conduct](CODE_OF_CONDUCT.md). If PersonalEvoTaste helps you, a ⭐ on GitHub goes a long way.

## 📜 License

MIT © PersonalEvoTaste Contributors. See [LICENSE](LICENSE).
