Metadata-Version: 2.4
Name: subactor-reflex
Version: 0.1.0
Summary: Evidence-first learning loop for agent and tool work
Author: Subactor
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Reflex

Reflex is a local, evidence-first observability and learning loop for agent
work. It ingests safe projections of sessions, tool calls, CI results and
delivery receipts from the Subactor, Semcod and Autogrammar ecosystem; it then
normalizes repeated events, detects recurring failure patterns and emits
bounded improvement proposals.

## What is delivered

The first release provides a deterministic, stdlib-only pipeline for JSONL,
NDJSON and bounded text evidence:

- secret and home-directory redaction, event normalization and duplicate
  collapse;
- recurring-pattern detection for governance, dependency, tool-contract,
  credential-readiness, remote-rate-limit and test-feedback failures;
- an optional SQLite store containing normalized evidence only, so observations
  can accumulate across sessions without retaining raw transcripts;
- a closed `reflexdsl` request format for bounded `INGEST`, `ANALYZE`, `REPORT`,
  `STATUS` and `PROPOSE` operations;
- an offline `status` projection with issue creation lists, open-resource
  counts, closed/merged pull requests, last closure time and closure history;
- an optional SubLLM reflection step that produces advisory hypotheses only.

The analysis and ownership recommendations are recorded in
[`docs/analysis/reflex-learning-loop.md`](docs/analysis/reflex-learning-loop.md).

## Quick start

From the assembled checkout:

~~~text
python -m venv .venv
pip install -e .
reflex analyze --source /path/to/safe/logs --store .subactor/cache/reflex.sqlite
reflex analyze --source /path/to/safe/logs --llm
reflex status --source /path/to/github-events.jsonl --format text
~~~

For a bounded DSL request:

~~~text
reflex dsl --request '```reflexdsl
ANALYZE ROOT "/path/to/safe/logs" MIN_REPEAT 3
```' --allowed-root /path/to/safe/logs
~~~

For lifecycle status, use the closed DSL command:

~~~text
reflex dsl --request '```reflexdsl
STATUS ROOT "/path/to/github-events.jsonl" FORMAT text
```' --allowed-root /path/to
~~~

Use a path outside the repository, or the ignored `.subactor/cache` area, for
the SQLite store. Reflex never treats a proposal as permission to create a
ticket, change code, merge a branch, deploy a service or publish a release.

## Operating boundary

Only bounded projections should be supplied as input. Raw chat transcripts,
credentials, private keys and unrestricted environment dumps are not inputs to
this project. Source lines are represented by digests and short redacted
summaries. The LLM is downstream of deterministic normalization and its output
is advisory; protected governance, ticket ownership and delivery controllers
remain authoritative.

The repository is intentionally initialized with the Wellmanifest governance
contract before implementation. See [`TODO.md`](TODO.md) for the next bounded
integration steps and [`docs/README.md`](docs/README.md) for the analysis index.
