Metadata-Version: 2.4
Name: hermes-context-engine
Version: 1.3.1
Summary: The psychological reasoning layer for AI sales agents.
Author: Hermes Context Contributors
License: MIT
Project-URL: Homepage, https://github.com/hermes-context-engine/hermes-context-engine
Project-URL: Bug Tracker, https://github.com/hermes-context-engine/hermes-context-engine/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: streamlit>=1.22.0
Requires-Dist: plotly>=5.14.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# 🔮 Hermes Context Engine

> The psychological reasoning layer for AI sales agents.

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Format](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**Hermes Context Engine** is a production-grade, local-first open-source psychological reasoning and context infrastructure layer. It transforms raw conversational logs (WhatsApp chats, Zoom transcripts, audio diarizations) into structured, Pydantic-validated psychographic profiles, behavioral models, objection intelligence indices, and financial Opportunity Gap matrices.

This is **not** a CRM, a simple chatbot, or a basic API wrapper. It is reusable **cognitive infrastructure** designed to give conversational AI agents deep, real-time psychographic reasoning capabilities.

---

## ✨ Core Architecture

* **Dual-Mode Processing Pipeline**:
  - **Offline-First Heuristics**: Local token-density matchers, rolling dialog statistics, and structural keyword inferences. Runs 100% offline out-of-the-box with **zero API keys** and zero latency.
  - **LLM Engine (LiteLLM)**: Integrates advanced reasoning models (GPT-4o, Claude 3.5 Sonnet, Gemini Pro, Llama-3) to produce high-fidelity psychographic profiles bound by strict Pydantic JSON contracts.
* **Certainty Triangle Core**: Estimates trust across three distinct vector axes:
  - `implementation_confidence`: Prospect confidence in the mechanism/logic (Vehicle).
  - `trust_confidence`: Prospect confidence in the seller/brand authority.
  - `self_efficacy`: Prospect internal belief to succeed in execution.
* **Opportunity Gap & COI**: Quantifies the financial gap (Current vs Desired Revenue) and calculates the **Cost of Inaction (COI)** to generate high-tension closing directives.
* **Objection Battlecards**: Automatically extracts verbal objections and pairs them with structured reframing rebuttals.
* **Cinematic Pressure Timeline**: Compiles rolling emotional turning points (skepticism spikes, curiosity, intent spikes) chronologically for dynamic telemetry visualization.

---

## 🚀 Quickstart (10 Seconds)

Ensure you have Python 3.9+ installed, then install the package:

```bash
pip install hermes-context-engine
```

### Basic Offline Usage

```python
from hermes_context import HermesContextEngine

# Initialize the engine in local-first offline mode
engine = HermesContextEngine(offline_mode=True)

# Define a sales conversation segment
transcript = """
Closer: Hola Carlos, gusto en saludarte. ¿Cómo te ha ido con los números en tu agencia?
Carlos: Hola. Facturamos unos $3,000 pero queremos llegar a $15,000. Nos sentimos estancados y no tenemos tiempo.
Closer: Entiendo. Si demoras 6 meses en cambiar esto, ¿cuánto te costará no tomar acción?
Carlos: Serían casi $72,000 en facturación perdida...
"""

# Analyze
analysis = engine.analyze(transcript, closer_name="Closer", prospect_name="Carlos")

print(f"DISC Profile: {analysis.buyer_profile.disc}")
print(f"Monthly Revenue Gap: ${analysis.opportunity_gap.monthly_gap:,}")
print(f"Cost of Inaction: ${analysis.opportunity_gap.cost_of_inaction:,}")
print(f"Estimated Probability of Conversion: {analysis.summary.close_probability}%")
```

---

## 🖥️ Command Line Interface (CLI)

The package compiles a gorgeous terminal binary called `hermes` utilizing Pydantic validation, `Typer`, and `Rich`.

### Run local-first transcript analysis
```bash
hermes analyze examples/transcripts/raw_call_es.txt
```

### Export a Notion-compatible Markdown briefing
```bash
hermes analyze examples/transcripts/raw_call_es.txt --format markdown --output briefing.md
```

### Start an interactive roleplay simulator session
```bash
hermes simulate --profile "Skeptical Founder" --objection "This feels too complex for our tech lead."
```

---

## 📊 Streamlit Glassmorphic Dashboard

Run the interactive dashboard to upload transcripts and view premium, highly visual psychographic charts:

```bash
streamlit run dashboard/app.py
```

### Features:
* **Executive Summary**: Radar polar charts tracking the **Certainty Triangle** trust vectors.
* **Telemetry Tab**: Interactive, cinematic **Pressure Timeline** charting skepticism spikes and intent density.
* **Objections battlecards**: Visual high-contrast card blocks matching explicit complaints with rebuttal copy.
* **Tactical Levers**: Automatic copy-paste strategic script suggestions.

---

## 🤝 AI Framework Integrations

Hermes Context Engine is designed from the ground up as modular **ecosystem software** to hook directly into popular multi-agent frameworks.

### LangChain Custom Tool

```python
from hermes_context.integrations import HermesContextLangChainTool

tools = [HermesContextLangChainTool()]
# The agent can now invoke 'hermes_context_analysis' within its reasoning loops!
```

### CrewAI Agent Tool

```python
from hermes_context.integrations import HermesContextCrewAITool

# Equip your Closer or Researcher agents directly
closer_agent = Agent(
    role="Sales Context Strategist",
    goal="Extract psychographic blockages from prospect call transcripts",
    backstory="You are a Closing Cuántico master analyzing verbal friction.",
    tools=[HermesContextCrewAITool()]
)
```

### LangGraph Stateful Node

```python
from hermes_context.integrations.langgraph import hermes_context_node
from langgraph.graph import StateGraph

builder = StateGraph(AgentState)
# Add hermes node to parse raw transcript and update state variables automatically
builder.add_node("psychographic_analyzer", hermes_context_node)
```

### Nous Research Hermes Agent Native Plugin

You can integrate this engine directly into the official autonomous **Nous Research Hermes Agent** framework as a native plugin:

1. Copy the plugin adapter directory into your local Hermes Agent plugins folder:
   ```bash
   cp -r integrations/hermes_agent/ ~/.hermes/plugins/hermes-context-engine
   ```
2. Enable the plugin inside your running Hermes terminal instance:
   ```bash
   hermes plugins enable hermes-context-engine
   ```
3. The LLM will now automatically discover, contextually understand, and call the `hermes_context_analysis` tool dynamically during conversational workflows!

---

## 📁 Repository Directory Structure

```txt
hermes-context-engine/
├── hermes_context/              # Core Package
│   ├── analyzers/               # Modular Psychological Calculators
│   │   ├── certainty.py         # Mappings for implementation, trust, self-efficacy
│   │   ├── disc.py              # DISC trait classifier
│   │   ├── friction.py          # Blocker and risk calculator
│   │   └── speaking_ratio.py    # Conversation density analytics
│   ├── integrations/            # AI Agent framework wrappers
│   │   ├── langchain.py         # LangChain tool adapter
│   │   ├── crewai.py            # CrewAI tool adapter
│   │   └── langgraph.py         # LangGraph node utility
│   ├── utils/                   # Dialogue parsers & clean tools
│   ├── exporters/               # Markdown, CRM, & JSON compilers
│   ├── prompts/                 # Core XML Pydantic system instructions
│   ├── cli.py                   # Rich terminal binary
│   └── engine.py                # Main engine orchestration
├── dashboard/                   # Streamlit App
│   └── app.py                   # Glassmorphic dark-mode analytics GUI
├── examples/                    # Sample resources
│   ├── minimal.py               # Copy-paste onboarding guide
│   └── transcripts/             # English/Spanish raw dialouge logs
├── benchmarks/                  # Performance benchmarks
│   ├── run_benchmarks.py        # Automated heuristics test runner
│   └── outputs/                 # Baseline JSON artifacts
├── tests/                       # Unit testing suite
│   └── test_engine.py           
├── pyproject.toml               # PyPI package dependencies
├── LICENSE                      # MIT
└── README.md                    # Core Documentation
```

---

## 📜 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
