CEEZ Ground · Enterprise semantic operating model
AI agents can’t operate an enterprise on data alone. They need to know what things mean, how work flows, which rules apply, what has to be decided, who may act, and what is happening now. Ground discovers that from your systems, has your people validate it, and compiles it so agents can use it.
python3 -m venv --system-site-packages .venv
.venv/bin/pip install -r requirements.txt
PGPASSWORD='…' .venv/bin/python server.py
# console: http://localhost:8899/appRead-only connection.No data leaves your machine unless you configure a model.
Illustration of the console · sample values
The problem
Each system holds a piece. The CRM knows the contract. Billing knows the revenue. Support knows the open issues. Product knows usage is falling. Renewal is 42 days away. Only people join those up.
“This strategically important customer is approaching renewal, usage is declining and support problems are growing, so the customer may be at risk.”
That sentence lives across relationships, processes, policies, decisions and people. It is rarely written down in one place.
Rows in separate tables with different names for the same customer, no rule about who may offer a discount, and no idea whether the figures it is reading are still current.
Today people do the connecting. That is the human semantic layer, and Ground’s job is to turn it, step by step, into something software can run on.
What an operating agent needs to hold together
The model
The Enterprise Semantic Operating Model isn’t a static ontology or a graph. It’s a representation of how the enterprise understands, operates, governs, decides and changes, kept current and available to the AI workforce. Business intent sits above it, and the six views are connected, not separate models.
What exists, and what does it mean?
Entities, attributes, definitions, relationships, identities, temporal meaning and the evidence behind each.
How does the enterprise perform this work?
Processes, stages, dependencies, events, exceptions, escalations and service levels.
What can, must or cannot happen?
Policies, limits, approvals, compliance rules, escalation conditions and what each agent may do.
Given what we know, what do we decide?
Triggers, criteria, alternatives, evidence needed, risk and escalation. A decision is not a policy: “offer 8%” versus “agents may offer up to 10%”.
Who is responsible for this work?
People, roles, teams, agents, systems and partners, with responsibility, capability and authority.
What is true now, and how did we get here?
Current and historical state, events, transitions and effective dates. Decisions depend on current state, not only on definitions.
Built, partly built, not yet. The status on each card describes this product today, so you can see how much of the model you get now and how much is the direction.
How it’s built and kept current
The model isn’t drawn once by hand. A Semantic Intelligence Workforce discovers, challenges and validates it continuously, and a compiler turns what’s proven into something agents can execute.
A standing team of AI roles with a loop that never stops.
Humans supervise the exceptions that matter and own governance. They aren’t asked to map the enterprise by hand.
AI discovers meaning. Deterministic systems execute meaning that has been established.
Top-down: what does the business want to achieve? Bottom-up: what does the enterprise actually contain? Ground reconciles the two.
An assertion isn’t just true or false. Safe autonomy needs more states.
Only a person can mark something Trusted. Unknown and contradicted concepts block execution.
From model to action
An agent shouldn’t receive the whole enterprise. Ground compiles what a mission needs, and every proposed action is checked against authority before it happens.
What the compiled context would contain.
Each step can carry different permissions, and each process sits on its own rung.
Before an agent acts: semantic validity, evidence, freshness, temporal validity, policy, decision authority, action authority, and risk. Eight checks return execute, block, downgrade or escalate.
Today this stops at the decision. Ground returns the decision and records it. There are no adapters that write to your systems, so connecting an action is a separate, deliberate step.
The loop that improves it
The loop doesn’t end when an agent acts. What happened, compared with what was expected, is evidence about the model itself.
Each action records the outcome expected and the outcome observed against the contract’s pinned measurement.
Schema, policy and definition changes are sensed, their blast radius is computed, and what rests on them is held back until revalidated.
A gap between expected and actual is a question about the model. It can reveal wrong knowledge, a missing relationship, stale state, a misread policy or bad decision logic. Ground traces it by provenance rather than guessing, and the Ground ratio tells you whether meaning is being confirmed faster than it goes stale.
The question leaders ask
This is the experience the model is built toward: readiness stated per dimension, with what’s missing and where a person must stay involved. A figure for illustration only.
Illustrative · customer renewal
Missing: executive sponsor relationship, renewal intervention history. Mode: policy-bounded autonomy. Human required: discounts over 10%.
Where this exists today. Per-concept trust, what an agent may act on, authority at risk and the autonomy level per process are computed now. A single readiness view across all six dimensions, and a navigable Knowledge Library, are the target. Today the human-facing views are Explore and the exportable data dictionary.
How it differs
Both stay useful as parts. Neither is the architecture.
| Approach | Answers | The operating model also answers |
|---|---|---|
| Knowledge graph | What is connected to what? | What does the enterprise mean, how does it operate, what rules govern it, who can act, what is happening, and what happened as a result? |
| RAG | What should I retrieve for this query? | What environment does this agent need to perform this mission: entities, state, rules, evidence, time and authority? |
| Manual enterprise model | What did we draw once? | What is true now, and who or what is keeping it true as the business changes? |
What you can do today
The console has five sections. Each is a job that adds to the model and ends with something you can show: a published record, a signed release, an answer with its evidence.
Add a PostgreSQL database or upload files. See how far it has come, from discovered through profiled, interpreted and reviewed to published.
Open Sources → Add a data source
One run reads the structure, profiles the columns, lets AI roles debate what they mean, and drafts a record. You choose how much data it may read.
Open Sources → Run discovery
Work through a deck of decisions, worst first. Approve a reading, dispute it, or clarify it. Only a person can mark something Trusted.
Open Review → Decisions
See where two sources define the same thing differently. Adopt one, define a new one, or keep both scoped. Nothing is merged silently.
Open Review → Conflicts
Stage a change as a release, run six gates against it, get a named approval if it widens authority, canary it, and roll back in one step.
Open Publish → Releases
Ask in plain language. Answers are built from the published meaning and show the SQL and evidence. If a concept is unknown, Ground says so instead of guessing.
Open Explore → Ask a question
Say what you want to know or do. Ground checks the data can support it, then compiles a versioned contract that limits what an agent may decide and do.
Open Operate → Business intents
An agent asks for a decision. Eight checks return execute, block, downgrade or escalate, and name the one that failed. Nothing is written to your systems.
Open Publish → Execution
One figure says whether meaning is being confirmed faster than it goes stale. It sets how much each process may be trusted to do.
Open Operate → Outcomes
Product tour
Illustrations of the console with sample values. Each shows the controls you actually get and where to find them.
Review
Every uncertain reading, conflict and policy exception lands in one deck. Open a card to see the evidence, then decide.
email_hashPublish
A re-read doesn’t overwrite what’s live. It becomes a candidate that has to pass before it replaces anything.
Explore
Questions resolve against the published meaning. Every answer carries the SQL that produced it and the claims it relied on.
inventory, stores, sales_daily
stockout risk per store
which stores to flag
draft a reorder (human approves above budget)
Operate
Register an intent and Ground compiles it into a versioned contract. The contract separates what an agent may decide from what it may do.
Day to day
Ground doesn’t ask for a new process. It adds four short routines to the ones you have.
Data steward or domain owner
Review → Decisions
Engineers and data teams
Terminal · CI
Approver with the data lead
Publish → Releases · Review → Conflicts
Risk, compliance, audit
Publish → Provenance · ledger.py
The same questions you already ask, answered in one place.
| When this happens | You used to | With Ground |
|---|---|---|
| A new analyst asks what a column means | Ask around, or read old queries. | Open the attribute. Read its meaning, scale, unit, trust level and history. |
| Two reports disagree | Reconcile by hand, argue about which is right. | See the conflict, with evidence on each side, and record the decision once. |
| A migration is planned | Hope nothing downstream breaks. | Run sotf check and see what depends on each column before merging. |
| Someone wants an agent to do a task | Debate whether to trust it at all. | Register the goal, compile a contract, start at human-approved, and graduate on evidence. |
| An auditor asks why something happened | Reconstruct it from logs and memory. | Follow intent → contract → evidence → decision, and show the receipt. |
| A policy document is revised | Tell people and hope they read it. | Re-read it. Rules bound to contracts are re-checked and affected authority is held back. |
Four figures to watch. They’re counted from recorded events, so you can put them in a review.
Is meaning being confirmed faster than it goes stale? Aim to stay above 1.0×.
Top of every screen
How many contracts read something they shouldn’t act on. This should trend to zero.
Top of every screen
How many cards are open and whether you’re clearing them. A growing pile means too little review time.
Review → Decisions
The share of registered business running within guardrails without a person on each action.
Operate → Outcomes
Step by step
Each task gives the click path and what changes when you finish it.
Sources → Projects → Add a data source
Entities, attributes and relationships drafted, with confidence on each.
Review → Decisions
Approvals are promotions: Ground rises and dependent contracts gain footing.
Review → Attributes
The correction is versioned, so history shows what it meant and when.
Publish → Releases
The decision is recorded with who and when.
Publish → Releases → the failing gate
The release goes back in front of a person, with the waiver attached.
Publish → Contracts
A suspended contract is excluded from every authority answer.
Terminal or CI
Exit code 1 on a breaking change, so the job fails. A GitHub format is available.
Publish → Releases
Live meaning only changes through a release, never by overwrite.
Publish → Checks
Without a connection a data test is reported unverifiable, not passed.
Operate → Business intents → Build an intent
A 10-point validation tells you what’s missing before it can compile.
Operate → Business intents → Implement
A versioned contract with a pinned measurement and authority grid.
API or MCP
Ground records the decision. It never writes to your systems itself.
Publish → Provenance
Shows the definition versions in force at that moment.
Terminal
Editing, deleting or reordering any entry breaks every hash after it.
Explore, or /register
A page a reviewer can read with no access to the platform.
Quickstart
You need Python 3 and a PostgreSQL database you can read. A model key is optional: without one only the deterministic engines run.
The server listens on 127.0.0.1 only. The connection defaults come from the usual PG* variables. Set SOTF_TOKEN now if you plan to call the API, otherwise the token is random on every start.
cd sotf-app python3 -m venv --system-site-packages .venv .venv/bin/pip install -r requirements.txt SOTF_TOKEN=change-me PGHOST=localhost PGUSER=readonly PGPASSWORD='…' \ .venv/bin/python server.py
Then open http://localhost:8899/app. The page you’re reading is served at /.
A source belongs to a project, so start there. Go to Sources → Projects and create one, say what it’s for, then open Add a data source. Choose A database, fill in host, port, user, database and password, test the connection, and add it. The connection is opened read-only.
Choose a data tier in the top bar (start at 0 or 1 if unsure what may be read). Open Sources → Run discovery and start it. It reads the schema, profiles the columns and, if a model key is set (SOTF_LLM_KEY), lets the AI roles debate what each one means. Without a key you get the deterministic results only. How long it takes depends on the size of the database.
curl -X POST localhost:8899/api/extract \
-H "X-SOTF-Token: change-me" -H "Content-Type: application/json" \
-d '{"db":"your_database","granted_tier":1,"with_model":false}'
curl "localhost:8899/api/extract/status?db=your_database" \
-H "X-SOTF-Token: change-me"Clear what you can under Review → Decisions. Then open Publish → The mapping and choose Publish the record. Once it’s published, Explore → Ask a question answers from it. To let others in, create tokens by role:
python3 identity.py add alice --role approver # prints her token once python3 identity.py add planner --role agent --agent # acts as agent:planner python3 identity.py grant your_database 1 # data tier for this database
Using it with more than one person? Set SOTF_LOCAL_ROLE=viewer so the console page isn’t a back door around everyone’s roles. Turn on four-eyes review per database once there is a second approver.
Who can do what
The server works out who is acting from their token. It doesn’t believe a name in a request. People and software can’t be confused: an agent can never hold approver or admin.
| Role | May |
|---|---|
| viewer | Read. |
| agent | Read, and ask the runtime for a decision. |
| operator | Everything above, plus extract, run cycles, publish references, and stop the fleet. |
| approver | Everything above, plus judge meaning, approve, reject, waive, promote and roll back releases, set contract status, and resume the fleet. |
| admin | Everything above, plus model configuration, roles, data-access grants and users. |
Use it from where you work
The same published meaning is available four ways.
The five-section web app, with a ⌘K bar that searches sources, entities, attributes, metrics, contracts and screens, and falls back to Ask.
Every screen is backed by an endpoint. Send a bearer token.
Check a schema change against the published meaning, without the server.
Give Claude Code, Cursor or any MCP client the verified meaning instead of raw schema.
Model health
Ground = (promotions + revalidations) ÷ (redefinitions + decays + disputes), over 7 days. Above 1.0× is gaining, 0.6 to 1.0× slipping, below 0.6× losing. Try how your week would read.
Illustrative model, not live data. Where nothing decayed, Ground shows no ratio rather than infinity.
Questions
The limits first, so you can decide quickly.
The knowledge map is the most complete, along with the policy and authority map, the semantic compiler (contracts), releases, the runtime decision checks, outcomes and the workforce that discovers and validates meaning. The decision, actor and state maps are partial. The process map and the readiness view and Knowledge Library are not built yet. The six cards under “The model” show the status of each.
No. The connection is opened read-only, queries run in read-only transactions with timeouts, and the SQL gate allows only single SELECTs against tables in the model.
Not yet. Ground evaluates the eight pre-commit checks and records what it decided, but there are no adapters that write to a source system. Connecting an action to a real system is a separate, deliberate step, and the checks exist to gate it when you take it.
PostgreSQL. Policy documents can be Markdown, HTML, DOCX or plain text. PDF is refused with the reason rather than half-read. Warehouses, applications and streams are not supported yet.
No, to start. The structural engines, tests, gates and runtime are deterministic. The key is needed for the interpretation debate. Set SOTF_LLM_KEY; a key typed into the console is kept in memory only, and you can restrict endpoints with an allow-list.
You decide per database with a tier. Tier 0 reads metadata only. Tier 1 reads distributions. Tier 2 reads governed samples. Below Tier 2 nothing that can return row content runs, and personal data is masked in profiles and results.
In JSON files in one state directory, written atomically, with damaged files flagged rather than silently overwritten. Governance decisions are appended to a hash-chained ledger you can verify.
Every figure opens a receipt with the claim, evidence, check and rule. Ground counts recorded events and never estimates them. Where it cannot tell, such as history before the store began, it says “unverifiable”.
Read-only, and on your own machine.