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)
• Subjective Context Estimation
• Time-Series Emotion Waves (emotionics.wave)
  • Concept: Time-Series Emotional Trajectory
  • Parameters
  • Code Example & Output Structure
• 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
  • Local LLM Support
  • 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"]
        TS["Transcript Array\n(youtube-transcript-api)"]
        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"]
        T --> Meta["estimate(mode='meta')\nSpeaker-perceived context hypotheses"]
        TS --> Wave["wave()\nTime-series chunking + parallel estimation"]
        A --> Ears["lend_ears()\nMultimodal transcription + emotion"]
    end

    Meta -. "Optional, user-reviewed hints" .-> Ctx

    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.10.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.

---

Subjective Context Estimation

emotionics.estimate(mode="meta") — Speaker-Perceived Context

mode="meta" infers hypotheses about the speaker's subjective, perceived communicative context from a text. The speaker's perception can differ from the actual, objective situation; this mode does not verify real-world identities, social roles, relationships, or audience reach. It helps prepare the four context arguments used by emotionics.gyo().

Output field	Estimated speaker-perceived context	Values
subject	How the speaker appears to position themselves in the exchange	Short descriptive string or null
circuit	How the speaker appears to perceive the intended communication topology	"1:1", "1:N", "N:1", "N:N", or null
power_gradient	How the speaker appears to perceive their relative power toward the target	"upward", "downward", "symmetrical", or null
intent	The apparent communicative goal or stance expressed in the text	Short descriptive string or null

Unknown is a valid result. When the text does not support an inference, the corresponding field is JSON null (Python None), rather than a fabricated value. For example, an aggressive tone does not establish a power gradient, and use of "you" does not establish whether a message is private or public.

The result also includes:

• perspective: "speaker_perceived" to distinguish the target of estimation from objective social facts.
• uncertainty: explanatory notes for unavailable or ambiguous fields; the reasons themselves are model-generated interpretations.
• gyo_kwargs: a dictionary containing only non-null fields suitable for use as arguments to gyo() after review.

Code Example

Activate an LLM provider first, as shown in Quick Start. The following example uses the already configured provider:

import json
import emotionics

text = (
    "Don't flatter yourself! People like you are completely "
    "ruining this industry and I will never let this go!"
)

meta = emotionics.estimate(text=text, mode="meta")
print(json.dumps(meta, ensure_ascii=False, indent=2))

Example output (observed with a locally hosted Gemma model; wording varies by model and run):

{
  "mode": "meta",
  "version": "0.10.0",
  "perspective": "speaker_perceived",
  "subject": "An adversary or critic",
  "circuit": null,
  "power_gradient": null,
  "intent": "Expressing strong condemnation and declaring continued opposition",
  "uncertainty": {
    "circuit": "It is unclear if the speaker perceives the communication as a private confrontation or a public rebuke.",
    "power_gradient": "The hostile and confident tone does not establish the speaker's perceived hierarchical standing relative to the target."
  },
  "gyo_kwargs": {
    "subject": "An adversary or critic",
    "intent": "Expressing strong condemnation and declaring continued opposition"
  }
}

Passing Estimated Context to gyo()

gyo() requires all four context values. meta["gyo_kwargs"] may omit unknown fields, so it cannot always be passed directly. Review the inferences and provide missing context only if you know it or explicitly choose a scenario to test:

# Continue from the preceding example.
gyo_context = {
    **meta["gyo_kwargs"],
    "circuit": "N:N",                  # Example scenario: open public network
    "power_gradient": "symmetrical",   # Example scenario: perceived peer relationship
}

required = ("subject", "circuit", "power_gradient", "intent")
missing = [key for key in required if not gyo_context.get(key)]
if missing:
    raise ValueError(f"Missing gyo context: {missing}")

result = emotionics.gyo(text=text, **gyo_context)
print(result)

The two supplied values in this example are illustrative assumptions, not deductions from the original text. There is no automatic gyo() call in mode="meta". You can also compare different plausible power gradients using gyo_matrix() when appropriate.

Interpretation and limits: All returned values are model-generated, uncertain hypotheses about language and possible speaker perception, not established facts about the speaker's mind or actual environment. A non-null value is not proof, and null is not necessarily a defect. Do not use these estimates as definitive profiling, psychological diagnoses, or high-stakes judgments. Results may vary across providers and models; no claim of validated inference accuracy is made.

---

Time-Series Emotion Waves (emotionics.wave)

Concept: Time-Series Emotional Trajectory

Human speech, video presentations, interviews, and podcasts evolve dynamically over time. Analyzing an entire transcript as a single flat block obscures critical emotional inflection points—such as sudden shifts into defensiveness, mounting anxiety, or breakthroughs of confidence.

emotionics.wave() processes timestamped transcripts (e.g., from youtube-transcript-api or ASR pipelines), groups utterances into fixed time intervals (default: 15.0 seconds), and executes parallel emotion estimation via concurrent.futures.ThreadPoolExecutor across all chunks while strictly preserving chronological timeline order.

Parameters

Parameter	Type	Default	Explanation
transcript_data	list[dict]	Required	List of transcript items containing at least text and start (seconds). Compatible with youtube-transcript-api.
interval	float	15.0	Time window for grouping and merging text chunks (in seconds).
mode	str	"lite"	Analysis mode for each chunk: "lite" (fast 5-axis) or "full" (45-element table & temporal vectors).
max_workers	int	min(10, N)	Concurrency limit for parallel ThreadPoolExecutor execution across chunks.

Code Example & Output Structure

import emotionics

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

# 1. Transcript data (e.g., from youtube-transcript-api or speech-to-text)
transcript = [
    {"text": "Welcome everyone. Today we have an important announcement regarding our roadmap.", "start": 0.5, "duration": 4.0},
    {"text": "We encountered critical unexpected roadblocks earlier this quarter that delayed our launch.", "start": 5.8, "duration": 5.2},
    {"text": "However, the engineering team rallied and engineered an outstanding breakthrough.", "start": 16.0, "duration": 5.0},
    {"text": "I am thrilled to finally reveal our new architecture today!", "start": 22.5, "duration": 4.1},
]

# 2. Analyze emotional wave across 15-second intervals (parallel execution)
wave_result = emotionics.wave(
    transcript_data=transcript,
    interval=15.0,
    mode="lite",  # or "full"
)

print(wave_result)

Example Output:

{
  "mode": "wave",
  "version": "0.10.0",
  "interval": 15.0,
  "timeline": [
    {
      "time_start": 0.0,
      "time_end": 15.0,
      "text": "Welcome everyone. Today we have an important announcement regarding our roadmap. We encountered critical unexpected roadblocks earlier this quarter that delayed our launch.",
      "analysis": {
        "mode": "lite",
        "version": "0.10.0",
        "trust": 0.72,
        "surprise": 0.35,
        "joy": 0.15,
        "fear": 0.65,
        "confidence": 0.88
      }
    },
    {
      "time_start": 15.0,
      "time_end": 30.0,
      "text": "However, the engineering team rallied and engineered an outstanding breakthrough. I am thrilled to finally reveal our new architecture today!",
      "analysis": {
        "mode": "lite",
        "version": "0.10.0",
        "trust": 0.90,
        "surprise": 0.20,
        "joy": 0.88,
        "fear": 0.05,
        "confidence": 0.94
      }
    }
  ]
}

---

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.10.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.10.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")

Local LLM Support

Emotionics can use a locally hosted LLM through its existing llm="openai" wrapper. A custom provider class is not required when the local server supports the API operations used by Emotionics (including the OpenAI Responses API). Install the OpenAI optional dependency:

pip install "emotionics[openai]"

Example: Connect to a local model

import os
import emotionics

# 127.0.0.1 works when the local LLM server and Python run on the same machine.
# For a server on another machine, set LOCAL_LLM_BASE_URL to its reachable URL.
base_url = os.getenv("LOCAL_LLM_BASE_URL", "http://127.0.0.1:1234/v1")
model = os.getenv("LOCAL_LLM_MODEL", "your-local-model-id")

emotionics.activate(
    llm="openai",
    api_key=os.getenv("LOCAL_LLM_API_KEY", "local-placeholder"),
    base_url=base_url,
    model=model,
)

result = emotionics.estimate(
    text="I was worried at first, but now I feel relieved.",
    mode="full",
)
print(result)

The project author has successfully tested this configuration with a locally served Gemma model (google/gemma-4-26b-a4b-qat) and estimate(mode="full"). The following result was observed in that test (results may vary by model and settings):

{
  "mode": "full",
  "version": "0.10.0",
  "candidate_emotions": [{"label": "Relief", "score": 0.95}],
  "temporal": {"direction_t1": "present", "d": 0.15},
  "temporal_distribution": {"past": 0.15, "present": 0.85, "future": 0.0},
  "intensity": 0.6,
  "politeness": 0.8,
  "sarcasm": 0.0,
  "directness": 0.9,
  "honesty_cues": 0.9
}

gyo() and gyo_matrix() have also been tested with a locally hosted Gemma model using the same connection approach.

The estimate(mode="meta") example above was also tested with a locally hosted Gemma model using this connection approach. The example demonstrates output formatting and unknown-field handling, not measured estimation accuracy.

Notes:

• Replace the model ID with the identifier exposed by your local server; it is not downloaded or installed by Emotionics.
• 127.0.0.1 refers to the machine running the Python script, not necessarily the machine hosting the LLM.
• The local-placeholder key is suitable only for a local endpoint that does not require real authentication.
• Not all OpenAI-compatible servers implement the Responses API; compatibility depends on the local server and model.
• If the server runs on another device, use a reachable hostname or LAN address and secure access appropriately.

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. Local LLM execution has also been tested using a Gemma model through an OpenAI-compatible endpoint. Other providers can be easily integrated via the custom provider interface.

Version

Emotionics v0.10.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.