Metadata-Version: 2.4
Name: entigram-ai
Version: 1.7.2
Summary: Schema-first semantic governance layer for enterprise agents
Author: Entigram Authors
License-Expression: Apache-2.0
Project-URL: Homepage, https://entigram.ai
Project-URL: Source, https://github.com/nyabutid/entigram
Project-URL: Documentation, https://entigram.ai
Project-URL: Tracker, https://github.com/nyabutid/entigram/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pysqlite3
Requires-Dist: pyyaml
Requires-Dist: networkx
Requires-Dist: inflect<7.3.0
Requires-Dist: protobuf>=5.26.1
Requires-Dist: requests
Requires-Dist: mcp>=1.0.0
Requires-Dist: cryptography>=42.0.0
Provides-Extra: ui
Requires-Dist: streamlit>=1.35.0; extra == "ui"
Dynamic: license-file

<p align="center">
  <img src="entigram/ui/media/logo.svg" alt="Entigram" width="520">
</p>

# Entigram: The Semantic Governance Layer for Enterprise Agents

**Entigram** is a schema-first control plane for enterprise agents that grounds agent behavior in verified domain models, approved semantic alignments, and auditable state transitions.

It provides the infrastructure to build **constrained autonomy**, ensuring that agents operate across fragmented enterprise systems without inventing fields, joins, entities, or state transitions.

## 🎯 The Entigram Thesis

Enterprise agent adoption fails when agents lack trustworthy domain context and enforceable schema boundaries. Entigram addresses this by sitting between your agents and your enterprise state.

> **Defensible Grounding:** Entigram prevents unsupported concepts and unverified mappings from entering operational agent workflows.

## 🛠️ Key Capabilities

- **Domain Boundaries (Schema):** Force agents to operate against explicit Entigram Schemas rather than vague natural-language context.
- **Closed-World Reasoning:** Automatically reject or quarantine unknown entities, attributes, and relationships.
- **Verified Semantic Alignments:** Enable cross-domain data federation using approved mappings instead of fuzzy LLM guesses.
- **Deterministic Conflict Handling:** Transform contradictory agent states into auditable ledger entries for human or policy-driven resolution.
- **Expectation Guard:** Convert modeled expectations, implementation rules, and validation checks into a runnable pre-handoff agent gate.
- **Agent Hydration:** Boot agents with exact project state, schemas, alignments, and settled decisions.
- **Auditability:** Store every alignment and decision in a local SQLite ledger for full provenance and governance.

## Core Workflow

1. **Model** the entities, attributes, and relationships agents are allowed to know.
2. **Gate** every proposed alignment, conflict, and state transition through MCP/CLI tools.
3. **Audit** accepted work with ledger evidence, delivery snapshots, and tamper-evident bundles.

## 🚀 Quickstart

### 1. Initialize a Governance Workspace
```bash
python3 -m entigram.cli_runner.etg_cli init --dir my-governed-agent
cd my-governed-agent
```

### 2. Define your Schema Contracts (Schema)
Create a `schema.lds` to define the entities and relationships your agents are allowed to "know."
```bash
ENTITY: Supplier
ATTRIBUTES:
  - .id (UUID)
  - name (String)
  - tax_id (String)
```

### 3. Hydrate and Launch
Align your agent's state vector with your local domain models:
```bash
python3 -m entigram.cli_runner.etg_cli agent --engine Antigravity
```

Before handoff, verify modeled expectations and record evidence:
```bash
python3 -m entigram.cli_runner.etg_cli broker guard
```

### 4. Run the Immutable Gate over MCP
Start the local MCP server from the governed workspace:
```bash
etg serve
```

Agents should discover schemas with `etg_get_schemas`, propose alignments with
`etg_propose_alignment`, and record deterministic conflicts with
`etg_log_conflict`. MCP responses use a stable JSON envelope:
```json
{"ok":false,"error":{"code":"UNKNOWN_CONCEPT","message":"Error: Invalid Schema Alignment - Entity Ghost not found","details":"Entity Ghost not found"}}
```

Successful proposals are written to the SQLite ledger configured in
`.etg/entigram.yaml`:
```yaml
schema_paths:
  - schema.lds
state_ledger: .etg/state.db
```

The server treats `schema_paths` as the closed-world boundary. Demo files,
templates, drafts, and unrelated LDS files are not exposed unless explicitly
listed.

Before returning work to a human reviewer:
```bash
etg broker guard
etg broker deliver
etg broker status
```

Export an Ed25519-signed audit bundle:
```bash
etg broker export-audit --out entigram-audit.json
```

The first export creates a local signing key at
`.etg/audit_ed25519_private.pem`. Keep that private key out of source control.

For the complete MCP tool contract, see [`docs/mcp-tools.md`](docs/mcp-tools.md).

Run the local Immutable Gate smoke demo:
```bash
python3 scripts/demo_immutable_gate.py
```

### Optional Dashboard

`etg ui` requires Streamlit. The CLI/MCP runtime is headless by default.

For pipx:
```bash
pipx install 'entigram-ai[ui]'
```

For an existing pipx install:
```bash
pipx inject entigram-ai streamlit
```

Homebrew installs are optimized for the CLI/MCP path. If `etg ui` reports that
Streamlit is missing, that is expected unless the dashboard dependency has been
installed into the same Python environment.

## 🏗️ How it Fits

Entigram is not an orchestration framework, MCP replacement, graph database, or IAM product. It is the **semantic governance layer** that complements those systems by providing:

1. **Schema Discipline:** Validating agent inputs/outputs against a strict Schema.
2. **Alignment Gates:** Ensuring cross-system joins (e.g., Salesforce Opportunity to Warehouse SKU) use verified mappings.
3. **Decision Ledger:** Providing a persistent, auditable record of state transitions.

```text
Agent framework
  -> Entigram semantic governance
  -> MCP/tools/connectors/databases
  -> enterprise systems
```

| Existing Layer | Examples | Entigram's Role |
| --- | --- | --- |
| Agent orchestration | LangGraph, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework | Validate domain state, mappings, payloads, and handoffs before agents act |
| Tool and data access | MCP, API tools, enterprise connectors | Govern tool schemas and block unsupported concepts or unverified mappings |
| Knowledge and context | RAG, GraphRAG, Neo4j, Stardog, data.world, LlamaIndex | Operationalize only verified concepts, relationships, and alignments |
| Runtime governance | RunAgents, Okta, policy engines, approval systems | Supply semantic policy signals and provenance for tool/action decisions |
| Observability | Tracing, OpenTelemetry, agent logs | Add semantic provenance: schema, alignment, evidence, conflict, and decision IDs |

## 🔒 Operational Principle

Discovery creates proposals, not operational facts.

Agents and routers may suggest alignments from schema similarity, partner data, or field names, but those proposals do not drive cross-domain joins until they are explicitly authorized with trusted evidence.

## 📈 Best-Fit Use Cases

- **Partner Reconciliation:** Normalizing and aligning external supplier data with internal systems.
- **Cross-Domain Integration:** Linking CRM data (Salesforce) to supply-chain or inventory forecasting.
- **Regulated Data Extraction:** Clinical/EHR extraction with strict validation and conflict gates.
- **Governance for Multi-Agent Ops:** Auditing the "handoff" state between different specialized agents.

## ⚖️ License

Entigram Core is Open Source under the Apache License 2.0.

---
*Entigram: Grounding agentic autonomy in enterprise reality.*
