Metadata-Version: 2.5
Name: kestrel-feature-reflection
Version: 0.4.0
Summary: Agent self-reflection and self-improvement feature for Kestrel Sovereign
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11.5
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: kestrel-sovereign-sdk<1,>=0.14.1
Requires-Dist: kestrel-sovereign<1,>=0.66.1
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# kestrel-feature-reflection

Agent self-reflection and self-improvement for Kestrel Sovereign.

## Installation

```bash
uv pip install kestrel-feature-reflection
```

The package registers `ReflectionFeature` through the `kestrel_sovereign.features`
entry point group.

## Conversation and memory boundaries

Version 0.4 requires Core 0.66.1 or newer. Reflection uses Core's canonical
speaker projection and escaped input boundaries. Connected clients' external
assistant transcripts remain quoted external data, rather than Kestrel's own
responses or actions. Memory excerpts are quoted as data as well.

Conversation reads go through the live privacy-aware conversation owner.
EPHEMERAL mode also excludes durable episode context and stored insights using
Core's existing privacy configuration predicate. Insight reads discard their
results if Core's privacy installation changes during retrieval.
Reflection sessions and insights use MemorySystem's existing persistence
permission and hold its privacy-transition lock through both original writes.
EPHEMERAL, ISOLATED and DEIDENTIFIED modes do not persist these derivatives.
Analysis retains Core's original privacy installation and its local-only model
requirement. A policy change discards old results before persistence or delivery,
even if the agent later returns to the same mode. Selected conversation excerpts
stay bounded after canonical rendering, with complete escaped input boundaries.

Tests cover native SQLite, privacy transitions, genuine native MCP source rows
and prompt construction with generation disabled. These checks do not establish
LLM judgment quality, a vendor account installation or an overnight deployment.

## Development

```bash
uv sync --extra test
uv run --extra test pytest
```
