cogext-primitive

Local commitment extraction for AI agents. No API key. No cloud. Just pip install.

Agents make promises — "I'll send the report to Sarah by Friday" — and almost nothing checks whether they kept them. This package extracts those commitments offline with pattern matching, parses the deadlines, and tracks each one through a state machine in a local SQLite file.

Nothing leaves your machine. There are no network calls in this library.

Install

pip install cogext-primitive

Quickstart

from cogext_primitive import extract_commitments

commitments = extract_commitments(
    "I'll send the report to Sarah by Friday EOD."
)

for c in commitments:
    print(f"{c.action} {c.object} to {c.recipient} by {c.deadline}")

send report to Sarah by 2026-09-25 23:59:59+00:00

CLI

cogext extract "I'll send the report by Friday"   # JSON, nothing stored
cogext add "I'll call Sarah tomorrow"             # extract + store
cogext list --status open                         # table of stored commitments
cogext get <commitment_id>                        # one commitment as JSON
cogext fulfill <commitment_id>                    # resolve it
cogext fail <commitment_id>
cogext stats                                      # counts by status

Zero configuration: the first command creates ~/.cogext/commitments.db.

$ cogext add "I'll email Sarah tomorrow"
3f2b1c44-9a7e-4c1b-8f0d-2a6e5b7c9d10  open  email  (confidence 0.95)

1 commitment(s) stored.

$ cogext list
ID        STATUS  ACTION  OBJECT  RECIPIENT  DUE (UTC)         CONF
--------  ------  ------  ------  ---------  ----------------  ----
3f2b1c44  open    email   -       Sarah      2026-09-24 23:59  0.95

What this does

• Extracts commitments from text using pattern matching — no LLM required
• Parses deadlines (by Friday, tomorrow, in 2 hours, by EOD, within 45 minutes)
• Distinguishes time-based commitments from event-based ones (once the tests pass)
• Tracks them through a state machine (detected → open → due → overdue → fulfilled)
• Stores them locally in SQLite, with resolved commitments frozen as terminal states
• Read-only commands (list, get, stats) do not create the database. Only write commands (add, fulfill, fail) do.
• Runs offline — no network calls, no telemetry, no account

The state machine

detected ─┬─> open ─┬─> due ──> overdue ─┬─> expired
          │         │                    ├─> fulfilled
          │         ├─> fulfilled        ├─> failed
          │         ├─> failed           └─> cancelled
          │         └─> cancelled
          └─> cancelled

fulfilled / failed / expired / cancelled are terminal and immutable.

Invalid transitions raise ValueError. Resolved commitments cannot be reopened — that is what makes the record trustworthy after the fact.

Extracted fields

What this deliberately skips

The extractor is precision-tuned, and returns nothing for:

• questions — "Should I send the report?"
• hypotheticals — "If we have time, I could send it"
• past-tense reports — "I sent the report yesterday"
• quoted third parties — "John said he would send it by Friday"
• vague obligations without a date — "I will handle that soon" (extracted at 0.85, no deadline)

This bias is measured, not guessed: in COGEXT Research 01 only 1 of 120 published agent outputs contained anything a rules-based extractor could recognise as a checkable commitment. Most agent output is narrative, tool traces or code.

What this doesn't do

• Verify commitments against external systems (Gmail, GitHub, webhooks)
• Produce cryptographic audit receipts
• Track commitments across multiple agents
• Score the quality of the evidence behind a claim

Those live in the cloud layer at cogextai.com. The primitive is free and MIT licensed; the verification engine is the paid product.

When to use this vs. the cloud

Use the primitive if you want to experiment locally without signing up, you are building a prototype and do not need verification yet, or you want to embed commitment extraction in your own tooling.

Use the cloud if you need external verification (did the email actually send?), audit trails and receipts, or you are running agents in production.

Two design decisions worth knowing

1. extract_commitments() returns commitments in detected state. Nothing is tracking them yet. CogextLocal.add() stores them as open, because adding a commitment is the act of starting to track it.
2. deadline is populated on the top-level model and mirrored in due_condition.deadline, so you never have to dig for the date. (The hosted API currently leaves the top-level deadline null; this library does not repeat that.)

Development

python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest
python -m build

License

MIT © 2026 Yamin / THRYVIX

Changelog

0.1.1

• Fix: list, get, and stats no longer create ~/.cogext/ or the SQLite schema on a clean machine. Read-only commands are now side-effect free.
• CogextLocal(...) can be constructed on a read-only filesystem.
• cogext stats with nothing tracked prints 0 commitments tracked. instead of a table of zeros.
• 8 new regression tests covering the above.

0.1.0

• First release: offline extraction, deadline parsing, lifecycle state machine, local SQLite storage, cogext CLI.