hatsu 0.1.0
A limited, observation-based emotion candidate suggester (non-intervening).
License: Apache-2.0
Requires Python: >=3.10
Keywords: emotion, ai-safety, emotion-analysis, non-intervening, governance

# hatsu
hatsu is a limited, observation-based emotion candidate suggester.

It does not provide advice, instructions, diagnosis, or psychological judgment.
It outputs informational candidates only, designed to support safe normalization of negative emotional states (e.g. moving negative signals closer to neutral).

hatsu is intentionally minimal, constrained, and responsibility-explicit.

## Quick Start (Recommended)
```python
import hatsu

hatsu.activate(
    api_key="YOUR_OPENAI_API_KEY",
    llm_model="gpt-4.1-mini",  # optional, default provided
)

result = hatsu.suggest(
    text="I'm worried about the future."
)

print(result)
```
## Example output:
```python
{
  "recommendations": [
    {
      "emotion": "Anxiety",
      "score": 0.93,
      "reason": "negative emotion; temporal=future",
      "recommendation_mode": "candidate_only",
      "meta": {
        "base_score": 0.9,
        "connectivity": 0.4,
        "temporal": {
          "direction": "future",
          "distance": 0.5
        }
      }
    }
  ],
  "excluded_candidates": [],
  "meta": {
    "mode": "conservative",
    "top_k": 5,
    "observer": "simple_observer",
    "llm_model": "gpt-5.2"
  }
}
```
⚠️ hatsu does not ship API keys, models, or hosted services.
All LLM usage is explicitly controlled by the user.

## Installation
### Development / Local Use
```bash
pip install -e .
```

### With OpenAI observer (optional)
```bash
pip install -e ".[openai]"
```

## What hatsu Does
hatsu provides:
	•	limited emotional candidate extraction
	•	structural negative-signal normalization support
	•	transparent time-axis annotation (past / present / future)

hatsu does not:
	•	give advice or instructions
	•	perform diagnosis or psychological evaluation
	•	decide actions or outcomes
	•	manipulate or coerce users
	•	store or transmit user data

hatsu is not a service.
It is a library with explicit responsibility boundaries.

## Design Overview
### Observe → Score Separation
hatsu strictly separates responsibilities:
	•	observer
	•	converts raw text into an EmotionEstimate
	•	replaceable (OpenAI-based, custom, offline, etc.)
	•	hatsu core
	•	scores and ranks candidates
	•	never intervenes or instructs

This separation is intentional and enforced.

### Activation
hatsu requires explicit activation before use.
```python
hatsu.activate(
    api_key="YOUR_OPENAI_API_KEY",
    llm_model="gpt-5.2",
)
```
If activate() is not called, hatsu raises an error.
There are no implicit defaults for external access.

### Built-in Observer
hatsu ships with a minimal built-in observer (simple_observer):
	•	observation-only
	•	optional OpenAI dependency
	•	conservative output schema
	•	no advice, no interpretation

Advanced users may replace it with their own observer:
```python
hatsu.activate(observer=my_custom_observer)
```

## Emotion Catalog
hatsu bundles its own emotion definition file:
	•	emotions.json (included in the package)

Users do not need to provide paths or configuration.
Advanced users may override it for research purposes.

## Responsibility Boundary (Important)
hatsu provides:
	•	structural candidate generation
	•	transparent scoring logic
	•	non-intervening output

Users are responsible for:
	•	API key handling
	•	model selection
	•	cost control
	•	data privacy
	•	legal and ethical compliance

There is no hidden responsibility transfer.

## Ethical Notes
hatsu processes emotional signals from text.

It is not:
	•	a medical tool
	•	a diagnostic system
	•	a psychological authority
	•	a decision-maker

Do not:
	•	use outputs as objective truth
	•	apply it to diagnosis or treatment
	•	use it for manipulation, coercion, or surveillance

hatsu is intended for:
	•	research
	•	experimentation
	•	reflective systems
	•	safety-oriented preprocessing
	•	foundational AI infrastructure

## Relationship to Emotionics
hatsu is conceptually related to Emotionics, but intentionally narrower.
	•	Emotionics: structural emotional estimation framework
	•	hatsu: limited, downstream candidate suggester

hatsu may be used as:
	•	a preprocessing layer
	•	a safety-oriented normalization component
	•	a building block inside larger systems (e.g. governance, AGI safety)

## Version

hatsu v0.1.0

## Project & Contact
hatsu is an experimental Python library focused on safe, limited emotional signal handling.

If you are involved in:
	•	AI safety
	•	governance
	•	foundational AGI research
	•	long-term system design

please contact:

📩 info@project-saya.com

Commercial exploitation, mass surveillance, or manipulative use is not the intended purpose of this project.