# alessandropcostabr/commercial-reasoner architecture

> Architecture diagram of the GitHub repository alessandropcostabr/commercial-reasoner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alessandropcostabr/commercial-reasoner
- Repository: https://github.com/alessandropcostabr/commercial-reasoner

## Overview

Commercial Reasoner is a stateless sales-reasoning service intended to work behind Hermes and the LATE integrator. LATE submits a turn and verified facts to `/reason`; the engine generates a reply, classifies commitments, checks monetary claims, then builds and signs an event for optional webhook delivery. The repository also includes a fact-extraction memory library, a persona/skill layer, and two documented alternative memory deployment stacks. The README describes their roles, but sampled source does not establish runtime wiring from Hermes to either stack. The graph reflects that limit rather than treating the alternatives as a connected dual-backend feature.

Main entry points: [`src/commercial_reasoner/service/reasoning.py`](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/reasoning.py) (Turn reasoning), [`src/commercial_reasoner/memory/extract.py`](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/extract.py) (Turn fact extraction), [`src/commercial_reasoner/memory/gate.py`](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/gate.py) (Response gate), [`src/commercial_reasoner/memory/numeric_guard.py`](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/numeric_guard.py) (Numeric checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Reasoning service"]
  node_app["HTTP API<br/>[app.py]"]
  node_reasoning["Turn reasoning<br/>[reasoning.py]"]
  node_llm["LLM generator<br/>[llm.py]"]
  node_commitment["Commitment classifier<br/>[commitment.py]"]
  node_contract["Event contract<br/>[contract.py]"]
end

subgraph group_memory["Fact and safety memory"]
  node_memory_api["Memory API<br/>[__init__.py]"]
  node_extract["Turn fact extraction<br/>[extract.py]"]
  node_rules["Rule extraction<br/>[rule_extractor.py]"]
  node_llm_extract["LLM candidate filter<br/>[llm_extractor.py]"]
  node_assembler["Fact assembler<br/>[assembler.py]"]
  node_canonical["Canonical facts<br/>[canonical_facts.py]"]
  node_gate["Response gate<br/>[gate.py]"]
  node_numeric["Numeric checks<br/>[numeric_guard.py]"]
  node_types["Memory types<br/>[types.py]"]
end

subgraph group_persona["Sales persona"]
  node_persona_file["Alma persona<br/>[SOUL.md]"]
  node_sales_skill["Sales skill<br/>[SKILL.md]"]
end

subgraph group_deploy["Gateway and memory deployments"]
  node_hermes(("Hermes gateway"))
  node_claude_mem[("claude-mem stack")]
  node_honcho[("Honcho stack")]
end

node_late(("LATE integrator"))
node_openrouter(("OpenAI-compatible LLM"))

node_late -->|"submits turn"| node_app
node_app -->|"processes request"| node_reasoning
node_app -->|"validates and signs"| node_contract
node_reasoning -->|"selects generator"| node_llm
node_reasoning -->|"classifies commitment"| node_commitment
node_reasoning -->|"builds facts"| node_canonical
node_reasoning -->|"checks reply"| node_gate
node_reasoning -->|"builds envelope"| node_contract
node_llm -->|"requests completion"| node_openrouter
node_llm -->|"loads persona"| node_persona_file
node_contract -->|"posts signed event"| node_late
node_memory_api -->|"exports extraction"| node_extract
node_memory_api -->|"exports conversion"| node_canonical
node_memory_api -->|"exports check"| node_gate
node_extract -->|"checks agent quote"| node_numeric
node_extract -->|"extracts signals"| node_rules
node_extract -->|"filters weak signals"| node_llm_extract
node_extract -->|"assembles result"| node_assembler
node_rules -->|"extracts numbers"| node_numeric
node_llm_extract -->|"returns candidates"| node_types
node_assembler -->|"uses numeric checks"| node_numeric
node_assembler -->|"builds facts"| node_types
node_canonical -->|"creates canonical facts"| node_types
node_gate -->|"checks numeric claims"| node_numeric
node_gate -->|"returns verdict"| node_types
node_hermes -.->|"routes conversations"| node_late
node_hermes -.-> node_claude_mem
node_hermes -.-> node_honcho
node_hermes -.-> node_sales_skill
node_late -.-> node_claude_mem
node_late -.-> node_honcho

click node_app "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/app.py"
click node_reasoning "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/reasoning.py"
click node_llm "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/llm.py"
click node_commitment "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/commitment.py"
click node_contract "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/contract.py"
click node_memory_api "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/__init__.py"
click node_extract "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/extract.py"
click node_rules "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/rule_extractor.py"
click node_llm_extract "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/llm_extractor.py"
click node_assembler "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/assembler.py"
click node_canonical "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/canonical_facts.py"
click node_gate "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/gate.py"
click node_numeric "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/numeric_guard.py"
click node_types "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/types.py"
click node_persona_file "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/hermes-alma/SOUL.md"
click node_sales_skill "https://github.com/alessandropcostabr/commercial-reasoner/blob/master/hermes-alma/skills/vendas/SKILL.md"
click node_claude_mem "https://github.com/alessandropcostabr/commercial-reasoner/tree/master/docker"
click node_honcho "https://github.com/alessandropcostabr/commercial-reasoner/tree/master/docker-honcho-distribuido"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_reasoning,node_llm,node_commitment,node_contract toneBlue
class node_memory_api,node_extract,node_rules,node_llm_extract,node_assembler,node_canonical,node_gate,node_numeric,node_types toneAmber
class node_persona_file,node_sales_skill toneMint
class node_hermes,node_claude_mem,node_honcho toneRose
class node_late,node_openrouter toneIndigo
```

## Components

### Reasoning service

- [HTTP API](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/app.py): `src/commercial_reasoner/service/app.py`
- [Turn reasoning](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/reasoning.py): `src/commercial_reasoner/service/reasoning.py`
- [LLM generator](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/llm.py): `src/commercial_reasoner/service/llm.py`
- [Commitment classifier](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/commitment.py): `src/commercial_reasoner/service/commitment.py`
- [Event contract](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/service/contract.py): `src/commercial_reasoner/service/contract.py`

### Fact and safety memory

- [Memory API](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/__init__.py): `src/commercial_reasoner/memory/__init__.py`
- [Turn fact extraction](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/extract.py): `src/commercial_reasoner/memory/extract.py`
- [Rule extraction](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/rule_extractor.py): `src/commercial_reasoner/memory/rule_extractor.py`
- [LLM candidate filter](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/llm_extractor.py): `src/commercial_reasoner/memory/llm_extractor.py`
- [Fact assembler](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/assembler.py): `src/commercial_reasoner/memory/assembler.py`
- [Canonical facts](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/canonical_facts.py): `src/commercial_reasoner/memory/canonical_facts.py`
- [Response gate](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/gate.py): `src/commercial_reasoner/memory/gate.py`
- [Numeric checks](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/numeric_guard.py): `src/commercial_reasoner/memory/numeric_guard.py`
- [Memory types](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/src/commercial_reasoner/memory/types.py): `src/commercial_reasoner/memory/types.py`

### Sales persona

- [Alma persona](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/hermes-alma/SOUL.md): `hermes-alma/SOUL.md`
- [Sales skill](https://github.com/alessandropcostabr/commercial-reasoner/blob/master/hermes-alma/skills/vendas/SKILL.md): `hermes-alma/skills/vendas/SKILL.md`

### Gateway and memory deployments

- **Hermes gateway**
- [claude-mem stack](https://github.com/alessandropcostabr/commercial-reasoner/tree/master/docker): `docker`
- [Honcho stack](https://github.com/alessandropcostabr/commercial-reasoner/tree/master/docker-honcho-distribuido): `docker-honcho-distribuido`

### Other components

- **LATE integrator**
- **OpenAI-compatible LLM**

## Connections

- LATE integrator → HTTP API: submits turn (evidence: `README.md`)
- HTTP API → Turn reasoning: processes request (evidence: `src/commercial_reasoner/service/app.py`)
- HTTP API → Event contract: validates and signs (evidence: `src/commercial_reasoner/service/app.py`)
- Turn reasoning → LLM generator: selects generator (evidence: `src/commercial_reasoner/service/app.py`)
- Turn reasoning → Commitment classifier: classifies commitment (evidence: `src/commercial_reasoner/service/reasoning.py`)
- Turn reasoning → Canonical facts: builds facts (evidence: `src/commercial_reasoner/service/reasoning.py`)
- Turn reasoning → Response gate: checks reply (evidence: `src/commercial_reasoner/service/reasoning.py`)
- Turn reasoning → Event contract: builds envelope (evidence: `src/commercial_reasoner/service/reasoning.py`)
- LLM generator → OpenAI-compatible LLM: requests completion (evidence: `README.md`)
- LLM generator → Alma persona: loads persona (evidence: `src/commercial_reasoner/service/llm.py`)
- Event contract → LATE integrator: posts signed event
- Memory API → Turn fact extraction: exports extraction (evidence: `src/commercial_reasoner/memory/__init__.py`)
- Memory API → Canonical facts: exports conversion (evidence: `src/commercial_reasoner/memory/__init__.py`)
- Memory API → Response gate: exports check (evidence: `src/commercial_reasoner/memory/__init__.py`)
- Turn fact extraction → Numeric checks: checks agent quote (evidence: `src/commercial_reasoner/memory/extract.py`)
- Turn fact extraction → Rule extraction: extracts signals (evidence: `src/commercial_reasoner/memory/extract.py`)
- Turn fact extraction → LLM candidate filter: filters weak signals (evidence: `src/commercial_reasoner/memory/extract.py`)
- Turn fact extraction → Fact assembler: assembles result (evidence: `src/commercial_reasoner/memory/extract.py`)
- Rule extraction → Numeric checks: extracts numbers (evidence: `src/commercial_reasoner/memory/rule_extractor.py`)
- LLM candidate filter → Memory types: returns candidates (evidence: `src/commercial_reasoner/memory/llm_extractor.py`)
- Fact assembler → Numeric checks: uses numeric checks (evidence: `src/commercial_reasoner/memory/assembler.py`)
- Fact assembler → Memory types: builds facts (evidence: `src/commercial_reasoner/memory/assembler.py`)
- Canonical facts → Memory types: creates canonical facts (evidence: `src/commercial_reasoner/memory/canonical_facts.py`)
- Response gate → Numeric checks: checks numeric claims (evidence: `src/commercial_reasoner/memory/gate.py`)
- Response gate → Memory types: returns verdict (evidence: `src/commercial_reasoner/memory/gate.py`)
- Hermes gateway → LATE integrator: routes conversations (evidence: `README.md`)
- Hermes gateway → claude-mem stack
- Hermes gateway → Honcho stack
- Hermes gateway → Sales skill
- LATE integrator → claude-mem stack
- LATE integrator → Honcho stack
