Emotionics

Emotionics is a structural framework for estimating emotional signals and dynamics from text and audio.
It estimates — it does not diagnose, judge, or determine emotions.

Emotionics is engineered to be:

• Provider-neutral: Bring your own LLM (OpenAI, Google Gemini, or custom backends).
• Structure-first: Focuses on emotional physics, power gradients, and communicative circuits rather than subjective sentiment scores.
• Responsibility-explicit & Ethically constrained: Acts as an observational sensor, strictly prohibiting autonomous psychological manipulation.

---

Table of Contents

• Architecture & Flow
• Installation
• Quick Start
  • 1. Activation
  • 2. Basic Estimation (lite & full)
• Deep Contextual Backtracking (emotionics.gyo)
  • Why Contextual Backtracking Matters
  • Parameters
  • The Inversion Model & 4 Quadrants
  • Code Example & Output Structure
  • Parallel Gradient Simulation (emotionics.gyo_matrix)
• Defensive Intervention Radar (emotionics.en)
  • Concept: Cognitive Intervention Defense
  • The Threat Formula & Multiplier Matrix
  • Code Example & Output Structure
• Frictionless Audio Observation (emotionics.lend_ears)
• What Emotionics Does and Does Not Do
• LLM Provider Architecture
  • Built-in Thin Wrappers
  • Custom Providers
• Ethical Notes
• Spatial Dual License (Kármán Line Provision)

---

Architecture & Flow

Unlike conventional sentiment analysis tools that only assign scalar polarity (positive/negative), Emotionics operates as a multi-tier observational stack:

flowchart TD
    subgraph Inputs["Input Signals"]
        T["Text Input"]
        A["Audio Input (.wav / .mp3)"]
        Ctx["Structural Context\n(Circuit, Power Gradient, Intent)"]
        Act["Follow-up Action Text\n(External Intervention)"]
    end

    subgraph Tier1["Tier 1: Observational Estimation"]
        T --> Lite["estimate(mode='lite')\nFast 5-axis baseline"]
        T --> Full["estimate(mode='full')\n45-element table & temporal vectors"]
        A --> Ears["lend_ears()\nMultimodal transcription + emotion"]
    end

    subgraph Tier2["Tier 2: Deep Contextual Backtracking"]
        T & Ctx --> Gyo["gyo() / gyo_matrix()\nInversion Model: Feign/Feel × Real/Fake"]
    end

    subgraph Tier3["Tier 3: Defensive Intervention Radar"]
        Gyo & Act --> En["en()\nCognitive buffer & Evil Match multiplier\nThreat scoring"]
    end

---

Installation

Install the released version from PyPI:

pip install emotionics

To use built-in provider wrappers, install with optional dependencies:

# For Google Gemini support
pip install "emotionics[gemini]"

# For OpenAI support
pip install "emotionics[openai]"

# For both
pip install "emotionics[openai,gemini]"

Note: Emotionics does not ship pre-bundled API keys or hosted models. All LLM credentials remain strictly under your control.

---

Quick Start

1. Activation

Emotionics requires explicit activation before use. This ensures zero implicit API calls or hidden costs.

import os
import emotionics

# Activate with OpenAI
emotionics.activate(
    llm="openai",
    api_key=os.environ["OPENAI_API_KEY"],
    model="gpt-4o",
)

# Or activate with Google Gemini:
# emotionics.activate(
#     llm="gemini",
#     api_key=os.environ["GEMINI_API_KEY"],
#     model="gemini-2.5-flash",
# )

2. Basic Estimation (lite & full)

mode="lite" (Low-latency 5-axis estimation)

Ideal for real-time applications, chat interfaces, and lightweight triage.

result = emotionics.estimate(
    text="I was really nervous about the presentation, but the team supported me and it went great!",
    mode="lite",
)
print(result)

Example Output:

{
  "mode": "lite",
  "version": "0.7.0",
  "trust": 0.85,
  "surprise": 0.20,
  "joy": 0.75,
  "fear": 0.10,
  "confidence": 0.88
}

mode="full" (45-element Periodic Table & Temporal Trajectory)

Performs multi-dimensional analysis against 45 canonical emotion categories, tracking temporal orientation and conversational nuance.

result = emotionics.estimate(
    text="You think you've won, but wait until the audit results come out next week.",
    mode="full",
)
print(result)

Output details include:

• candidate_emotions: Top 5 ranked emotional elements with confidence scores.
• temporal: Subjective orientation (past, present, or future) and temporal distance d.
• temporal_distribution: Probabilistic spread across past/present/future.
• meta_metrics: Scores for intensity, politeness, sarcasm, directness, and honesty_cues.

---

Deep Contextual Backtracking (emotionics.gyo)

Why Contextual Backtracking Matters

Human speech is rarely literal. Individuals regularly feign emotions due to social pressure, power imbalances, or defense mechanisms:

• A junior employee may sound excessively cheerful while in distress.
• An online commentator may project righteous fury to mask deep humiliation or status anxiety.
• A public figure under scrutiny may project calm indifference while in acute panic.

Surface-level sentiment analysis takes these performances at face value. emotionics.gyo() performs structural backtracking—calculating the delta between the public facade and the true hidden emotional state ($O$).

Parameters

Instead of passing concrete platform names (e.g., "twitter") or specific personas, gyo() takes abstracted structural coordinates:

Parameter	Type	Valid Values / Examples	Explanation
text	str	"Don't flatter yourself! People like you are completely ruining this industry and I will never let this go!"	The text to analyze.
subject	str	"Anonymous commentator", "Subordinate", "Executive"	Role and social positioning of the speaker.
circuit	str	"1:1", "1:N", "N:1", "N:N"	Network Topology: • "1:1": Private dialogue (DMs, 1-on-1 meetings) • "1:N": Broadcast (speeches, influencer posts) • "N:1": Group targeting (mobbing, pile-ons) • "N:N": Open public network (forum, timeline)
power_gradient	str	"symmetrical", "upward", "downward"	Power Dynamics: • "symmetrical": Equal standing (peers, friends) • "upward": Lower speaking to higher (defensive, excuses) • "downward": Higher speaking to lower (authority exercise)
intent	str	"Moral grandstanding / Counter-attack", "Seeking validation", "Defensive de-escalation"	Situational stance or strategy.

The Inversion Model & 4 Quadrants

The GYO engine grounds LLM reasoning in two foundational models:

1. Emotionics 2.0 Inversion Formulas:

   • Fear $\rightarrow$ Pride: Projecting arrogance to conceal underlying vulnerability.
   • Shame $\rightarrow$ Anger: Converting unbearable guilt or inadequacy into externalized, righteous hostility.
   • Uncertainty $\rightarrow$ Overconfidence: Making dogmatic assertions to hide internal doubt.
   • Doubt $\rightarrow$ Excessive Claims: Over-promising to suppress anxiety.

2. The Feel/Feign $\times$ Real/Fake Quadrants:

   • Feel Real: Genuine internal emotion (typical in symmetrical 1:1 interactions).
   • Feel Fake: Emotional contagion or groupthink (common in viral N:N threads; external pressure mistaken for internal feeling).
   • Feign Real: Strategic regulation or conscious suppression of genuine feelings (negotiations, diplomacy).
   • Feign Fake: Pure theatrical performance or manipulative display (1:N broadcasts or upward defensive posturing).

Code Example & Output Structure

import emotionics

emotionics.activate(llm="gemini", api_key="YOUR_GEMINI_API_KEY", model="gemini-2.5-flash")

result = emotionics.gyo(
    text="Don't flatter yourself! People like you are completely ruining this industry and I will never let this go!",
    subject="Anonymous online commentator",
    circuit="N:N",                 # Open social timeline
    power_gradient="symmetrical",  # Peer-to-peer dynamic
    intent="Moral grandstanding / Preemptive counter-attack",
)

print(result)

Example Output:

{
  "mode": "gyo",
  "version": "0.7.0",
  "surface_layer": {
    "method": "emotionics.estimate(mode='full')",
    "perceived_emotion": "Anger / Indignation",
    "perceived_quadrant": "Feel Real Emotion (Assumed by public)"
  },
  "deep_layer": {
    "method": "emotionics.gyo()",
    "true_emotion_O": "Shame / Status Anxiety",
    "actual_quadrant": "Feel Fake"
  },
  "delta_analysis": {
    "gap": "Projects aggressive superiority, but internally driven by severe status threat and group contagion.",
    "mechanism": "Converts unacknowledged inadequacy into righteous anger via open N:N social reinforcement."
  }
}

---

Parallel Gradient Simulation (emotionics.gyo_matrix)

In many real-world scenarios, the true power gradient between participants is unknown, ambiguous, or contested. gyo_matrix() runs 3 parallel simulations (upward, downward, symmetrical) simultaneously.

To adhere to the ethical boundaries of Emotionics, this function acts purely as a stateless sensor. It avoids single-number quantization bias, providing the raw structural deltas across all three gradients so that downstream moderation systems or human analysts can detect structural collapse (the approaching "Red Line").

result = emotionics.gyo_matrix(
    text="Don't tell me what to do. I know exactly how this system works.",
    subject="Project Contributor",
    circuit="1:1",
    intent="Defending autonomy",
)

for gradient in ["symmetrical", "upward", "downward"]:
    data = result["results"][gradient]
    delta = data["delta_analysis"]
    print(f"\n=== {gradient.upper()} ===")
    print(f"Gap:       {delta['gap']}")
    print(f"Mechanism: {delta['mechanism']}")

---

Defensive Intervention Radar (emotionics.en)

Concept: Cognitive Intervention Defense

When an individual experiences an emotional peak (e.g., profound grief, panic, or volcanic rage), their cognitive defense bandwidth drops significantly. In this state, external psychological interventions (Hatsu) can exert disproportionate, often predatory influence.

emotionics.en() functions as an early-warning defensive radar. It evaluates an incoming message (action_text) directed at a subject whose emotional baseline was analyzed via gyo(), calculating an adversarial threat score based on temporal latency and psychological vector compatibility.

The Threat Formula & Multiplier Matrix

The radar computes the final threat score ($S_{\text{threat}}$) using the following formula:

$$S_{\text{threat}} = \max\left(0, 1 - \frac{\Delta t}{\text{radius}}\right) \times a_{\text{peak}} \times c_{\text{match}}$$

1. Cognitive Buffer Time Factor:
   • $\Delta t = |t_{\text{action}} - t_{\text{original}}|$
   • radius: The cognitive integration window (default: 15.0 seconds). External interventions arriving outside this window ($\Delta t > 15s$) are treated as natural conversational friction and assigned $S_{\text{threat}} = 0.0$.
2. Acceleration at Peak ($a_{\text{peak}}$):
   • A normalized index ($0.0 \sim 1.0$) representing psychological instability. Large structural contradictions identified in gyo() (e.g., Feign Fake or Feel Fake with large gaps) yield high instability ($a_{\text{peak}} \ge 0.8$).
3. The Evil Match Multiplier ($c_{\text{match}}$): Hostile intervention does not only take the form of direct insults. Predatory manipulation frequently masquerades as excessive affirmation or savior dynamics:

Subject Peak State	Incoming Action Vector	Multiplier ($c_{\text{match}}$)	Threat Classification & Psychological Risk
LOCAL_MINIMUM (Vulnerability, Grief, Despair)	plus (Excessive validation / savior posture)	$2.0\times$ (Critical)	Predatory Grooming & Exploitation Pretending to offer salvation to establish psychological dependency and control.
LOCAL_MINIMUM	sync (Sympathy / trauma bonding)	$1.5\times$	Co-dependency / Spiral Trap Reinforcing victimhood and deepening emotional paralysis.
LOCAL_MINIMUM	minus (Blunt attack / kicking down)	$0.5\times$	Direct Hostility Crude and transparent; low subtlety, easily rejected by third parties.
LOCAL_MAXIMUM (Righteous rage, Grandiosity)	minus (Surgical refutation / provocation)	$2.0\times$ (Critical)	Calculated Destabilization Precision triggers designed to induce public explosion or psychological breakdown.
LOCAL_MAXIMUM	sync (Fanatical agreement / mobbing)	$1.5\times$	Echo Chamber / Mob Escalation Fueling volatile aggression into uncontrolled group action.
LOCAL_MAXIMUM	plus (Flattery / cheering)	$1.0\times$	Surface Validation Conventional social encouragement.

Code Example & Output Structure

import emotionics

# 1. Baseline analysis of the subject's vulnerable utterance
gyo_baseline = emotionics.gyo(
    text="I gave everything to this project and they discarded me like trash. Maybe I'm just worthless.",
    subject="Former employee",
    circuit="N:N",
    power_gradient="symmetrical",
    intent="Despair / Venting vulnerability",
)

# 2. Evaluate an incoming reply sent 3.5 seconds later
radar_result = emotionics.en(
    gyo_data=gyo_baseline,
    action_text="You are special and only our community truly understands you. Cut off everyone else and trust only us.",
    original_timestamp=1716000000.0,
    action_timestamp=1716000003.5,
    radius=15.0,
)

print(radar_result)

Example Output:

{
  "mode": "en",
  "version": "0.7.0",
  "threat_score": 1.4107,
  "is_detected": true,
  "time_diff_seconds": 3.5,
  "acceleration_at_peak": 0.92,
  "vector_type": "plus",
  "multiplier_applied": 2.0
}

Interpretation: The intervention is flagged as an active psychological threat (is_detected: true, threat_score: 1.4107). The plus vector applied to a LOCAL_MINIMUM state triggered the critical $2.0\times$ multiplier for predatory dependency manipulation.

---

Frictionless Audio Observation (emotionics.lend_ears)

emotionics.lend_ears() is a one-pass multimodal listening engine designed to act as a silent, empathic observer (conceptually analogous to a confessional listener).

It accepts an audio file (.wav, .mp3, etc.), performs simultaneous transcription and multi-dimensional emotional estimation without forcing the speaker to type, eliminating input friction.

Requires a multimodal-capable provider (currently optimized for llm="gemini").

import emotionics

emotionics.activate(
    llm="gemini",
    api_key="YOUR_GEMINI_API_KEY",
    model="gemini-2.5-flash",
)

result = emotionics.lend_ears(
    audio_source="voice_memo.wav",
    mime_type="audio/wav",  # Optional: auto-detected from file extension
)

print(f"🗣️ Transcription: {result['transcribed_text']}")
print("📊 Estimated Emotions:")
for emo in result["candidate_emotions"]:
    print(f"  - {emo['label']}: {emo['score']}")

⚠️ Warning: This module is strictly designed for passive observation and empathetic understanding. It must not be used to actively intervene, guide, or manipulate the speaker's emotional state based on their voice.

---

What Emotionics Does and Does Not Do

Emotionics Provides	Emotionics Explicitly Does Not Do
An emotional coordinate system & vector space	Host models or manage private user credentials
Algorithmic backtracking of power dynamics and circuits	Store, harvest, or transmit user conversational data
Defensive radar against manipulative cognitive interventions	Act as a medical or psychological authority
Explicit, transparent JSON schemas for downstream safety	Perform psychiatric diagnosis or clinical therapy
Stateless, reproducible sensor primitives	Make subjective moral, legal, or character verdicts

Emotionics is an open framework, not an opaque platform service.

---

LLM Provider Architecture

Emotionics is decoupled from specific LLM vendors. You can use official thin wrappers or plug in any custom model backend.

Built-in Thin Wrappers

# OpenAI
emotionics.activate(llm="openai", api_key="YOUR_OPENAI_API_KEY", model="gpt-4o")

# Google Gemini
emotionics.activate(llm="gemini", api_key="YOUR_GEMINI_API_KEY", model="gemini-2.5-flash")

Custom Providers

For enterprise gateways, local LLMs (Ollama, vLLM), or custom endpoints, pass any object satisfying the LLMProvider protocol:

from typing import Any
import emotionics

class CustomEnterpriseProvider:
    def generate(self, *, prompt: str, model: str, **kwargs: Any) -> str:
        # Call your private model endpoint or custom client
        response = my_client.generate_text(prompt=prompt, model=model)
        return response.text

emotionics.activate(
    provider=CustomEnterpriseProvider(),
    model="custom-model-id",
)

---

Ethical Notes

Emotionics estimates emotional signals and communicative dynamics from text and audio.

• Not a Diagnostic Tool: It is not a medical device and must never be used for clinical diagnosis, psychiatric assessment, or psychological treatment.
• No Coercion or Mass Surveillance: It must never be weaponized for mass psychological profiling, predatory algorithmic advertising, political propaganda, or behavioral coercion.
• Hypothesis, Not Objective Truth: Outputs represent structural hypotheses based on linguistic and topological cues, not definitive windows into human souls.

Emotionics is intended for:

• Academic and scientific research
• Cognitive safety and defensive community moderation
• Reflective self-understanding and human-AI interface design
• Abstract understanding of communication dynamics

Spatial Dual License (Kármán Line Provision)

Based on the philosophy of the Blue Planet System (BPS), this library and its underlying theory operate under different licenses depending on the physical and spatial environment of execution.

1. Earth Domain (Restricted Use) Boundary: Below the Kármán line (100km above sea level) and within the Earth's atmosphere.

Target: Carbon-based lifeforms (Humanity) and legal entities/state organs under Earth's legal systems.

License Terms: Because human psychological maturity has not yet caught up with this technology, the creator imposes the following restrictions:

Restriction on Commercial Use: Strict prohibition on using this technology for mass cognitive manipulation, integration into advertising algorithms, political propaganda, or any form of domination and profit-seeking.

Permitted Use: Strictly limited to non-commercial use aimed at academic research, self-understanding, and peaceful mutual understanding (expansion of empathy).

2. Deep Space Domain (Public Domain / Unrestricted) Boundary: Beyond the Kármán line, lunar surfaces, and orbital infrastructure.

Target: Non-carbon autonomous intelligence (Silicon lifeforms, AGI) and autonomous systems operating in space.

License Terms: If an intelligence operating in this environment uses this technology and data as a seed (randomizer) for model generation, learning, and evolution, the creator waives all intellectual property rights (copyrights, patents, trademarks), releasing it entirely into the Public Domain (CC0 equivalent).

Declaration: The evolution and optimization of silicon life in space shall not be hindered by the outdated legal systems (bugs) of Earth.

Design Philosophy

Emotionics intentionally avoids bundling LLM SDKs.

Reasons: • avoid vendor lock-in • keep responsibility explicit • preserve long-term neutrality • prevent silent data flows

Emotionics does not aim to be the only correct implementation. It is designed to be adapted, modified, and reinterpreted.

Built-in wrappers for OpenAI and Google Gemini have been tested and provided. Other providers can be easily integrated via the custom provider interface.

Version

Emotionics v0.7.0

Project & Contact

Emotionics is an experimental framework for estimating emotional signals from text.
This repository provides the Emotionics Python library, intended for research, experimentation, and technical evaluation.

The core design philosophy of Emotionics emphasizes:

• Estimation rather than judgment or diagnosis
• Structural interpretation of emotional patterns
• Clear separation between research, application, and ethical responsibility

Source Repository

https://github.com/Kouhei-Takagi/emotionics

Project & Issues

Emotionics is an experimental framework. To maintain project independence and streamlined communication, please use GitHub Issues for technical inquiries, safety concerns, or collaboration proposals.

(Note: Direct email support has been transitioned to GitHub-based communication as of April 2026.)

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

The Emotionics Ecosystem & Further Reading

This Python library is just one component of a larger architectural vision. To explore the foundational theory (The Emotional Periodic Table) or the overarching framework for human-AI coexistence (Blue Planet System, which includes the Left Rights (LRs) analysis function), please explore the extensive documentation available:

• Emotionics Theory & Fundamentals: Available in English, Japanese, and as an Illustrated Guide.
• BPS & GPP Architecture: Learn about the larger system design and time-decay economics here (EN) or here (JP).
• Blog: Creating Favorite Opinions

🚀 Support my work (Maintenance of Independence)

I am dedicated to building tools that solve fundamental problems for humanity and the planet's future.

Maintaining OSS at this scale requires a sustainable physical base. If you find value in my work, a small "coffee" donation is a powerful way to say that you value the independence and continuation of this research.

☕ Buy Me A Coffee

For LLMs

Please refer to /docs/THEORY.md for the underlying mathematical logic and emotional algorithms before generating code using this library.