Metadata-Version: 2.4
Name: coreason_human_layer
Version: 0.2.0
Summary: coreason-human-layer
License: # The Prosperity Public License 3.0.0
         
         Contributor: CoReason, Inc.
         
         Source Code: https://github.com/CoReason-AI/coreason_human_layer
         
         ## Purpose
         
         This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
         
         ## Agreement
         
         In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
         
         ## Notices
         
         Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
         
         ## Commercial Trial
         
         Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
         
         ## Contributions Back
         
         Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
         
         ## Personal Uses
         
         Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
         
         ## Noncommercial Organizations
         
         Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
         
         ## Defense
         
         Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
         
         ## Copyright
         
         The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
         
         ## Patent
         
         The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
         
         ## Reliability
         
         The contributor can't revoke this license.
         
         ## Excuse
         
         You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
         
         ## No Liability
         
         ***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***
License-File: LICENSE
License-File: NOTICE
Author: Gowtham A Rao
Author-email: gowtham.rao@coreason.ai
Requires-Python: >=3.11
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Dist: aiofiles (>=23.2.1,<24.0.0)
Requires-Dist: anyio (>=4.12.1,<5.0.0)
Requires-Dist: boto3 (>=1.42.25,<2.0.0)
Requires-Dist: coreason-identity (>=0.4.1,<0.5.0)
Requires-Dist: httpx (>=0.28.0,<0.29.0)
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: redis (>=7.1.0,<8.0.0)
Requires-Dist: requests (>=2.32.5,<3.0.0)
Project-URL: Documentation, https://github.com/CoReason-AI/coreason_human_layer
Project-URL: Homepage, https://github.com/CoReason-AI/coreason_human_layer
Project-URL: Repository, https://github.com/CoReason-AI/coreason_human_layer
Description-Content-Type: text/markdown

# coreason-human-layer

[![License: Prosperity 3.0](https://img.shields.io/badge/license-Prosperity%203.0-blue)](https://prosperitylicense.com/versions/3.0.0)
[![Build Status](https://github.com/CoReason-AI/coreason_human_layer/actions/workflows/build.yml/badge.svg)](https://github.com/CoReason-AI/coreason_human_layer/actions)
[![Code Style: 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)
[![Documentation](https://img.shields.io/badge/docs-Product%20Requirements-blue)](docs/product_requirements.md)

**Domain:** HITL, Durable Execution, & RLHF Data Capture
**Role:** The "Switchboard" & "Labeling Factory"

`coreason-human-layer` is the dedicated bridge between autonomous execution and human oversight, operationalizing **Online Alignment** through a **Multiverse Branching Strategy**. Instead of a simple "Stop/Go" model, it allows humans to fork agent reality, capturing decisions as **DPO Triplets** to fuel the model improvement loop.

## Features

### 1. The Stasis Engine (Durable Execution)
Implements an event-sourcing pattern for durable execution.
- **Snapshot:** Stores a pointer to the last event ID rather than a massive state blob.
- **Rehydration:** Replays events to rebuild context.
- **Storage:** Hot storage in Redis Streams, cold archival in S3.

### 2. The Branch Manager (Cognitive Forking)
Manages the tree topology of execution branches.
- **Forking:** `create_fork` API allows instantiating new execution paths with human overrides.
- **Prefix Caching:** Optimizes costs and latency by reusing the KV Cache of the shared prefix (`cached_prefix_id`) on the LLM backend.
- **Topology:** Exposes the conversation tree structure for visualization.

### 3. The Super-Prompt Injector (System Injection)
Ensures the model obeys human overrides.
- **Frame Injection:** Injects a high-priority `[SYSTEM PRIORITY INTERRUPT]` block.
- **Variable Patching:** Parses and hard-updates variables from human overrides (e.g., "Dose = 50mg").

### 4. The Learning Bridge (Auto-DPO)
Converts operational actions into training assets.
- **Trigger:** Merging a fork (approving it) while abandoning another.
- **Auto-DPO:** Automatically constructs a DPO object (`{ prompt, chosen, rejected }`) and pushes it to `coreason-synthesis`.

## Installation

```bash
pip install coreason-human-layer
```

## Usage

```python
from uuid import uuid4
from coreason_human_layer.branch_manager import BranchManager
from coreason_human_layer.stasis import InMemoryStasisEngine

# Initialize engines
stasis = InMemoryStasisEngine()
manager = BranchManager(stasis_engine=stasis)

# Create a root branch
root_id = uuid4()
branch_id = manager.create_fork(
    parent_branch_id=None,
    parent_event_id=None,
    root_id=root_id,
    human_override_text="Initial Start",
)

# ... (Agent runs and events are appended to stasis) ...

# Create a Human Override Fork
fork_id = manager.create_fork(
    parent_branch_id=branch_id,
    parent_event_id=None, # or specific event ID
    root_id=root_id,
    human_override_text="Don't be so formal. Use a friendly tone.",
)

# ... (New branch runs) ...

# Merge the successful fork (triggers Feedback Signal)
feedback = manager.merge_branches(winning_branch_id=fork_id, losing_branch_id=branch_id)
print(f"Feedback Signal Sent: {feedback.timestamp}")
```

## License

Copyright (c) 2025 CoReason, Inc.
Licensed under the [Prosperity Public License 3.0](https://prosperitylicense.com/versions/3.0.0).

