🔮 Hermes Context Engine

The psychological reasoning layer for AI sales agents.

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:

pip install hermes-context-engine

Basic Offline Usage

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

hermes analyze examples/transcripts/raw_call_es.txt

Export a Notion-compatible Markdown briefing

hermes analyze examples/transcripts/raw_call_es.txt --format markdown --output briefing.md

Start an interactive roleplay simulator session

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:

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

from hermes_context.integrations import HermesContextLangChainTool

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

CrewAI Agent Tool

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

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:

   cp -r integrations/hermes_agent/ ~/.hermes/plugins/hermes-context-engine
   

2. Enable the plugin inside your running Hermes terminal instance:

   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

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 file for details.