Metadata-Version: 2.5
Name: cogext-primitive
Version: 0.1.0
Summary: Local, offline commitment extraction and tracking for AI agent output. No API key, no cloud, no signup.
Project-URL: Homepage, https://cogextai.com
Project-URL: Repository, https://github.com/yaminbinyoosuf/cogext-primitive
Project-URL: Documentation, https://cogextai.com/research/01/
Project-URL: Changelog, https://github.com/yaminbinyoosuf/cogext-primitive/releases
Project-URL: Bug Tracker, https://github.com/yaminbinyoosuf/cogext-primitive/issues
Author-email: Yamin / THRYVIX <hello@cogextai.com>
License-Expression: MIT
License-File: LICENSE
Keywords: accountability,ai-agents,commitments,llm,promise-tracking,reliability,state-machine
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.8
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install cogext-primitive
```

## Quickstart

```python
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

```bash
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
- 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

| Field | Meaning |
|---|---|
| `promise_text` | The sentence the promise came from |
| `action` | The verb: `send`, `email`, `deploy`, `follow up` |
| `object` | What is being acted on: `report`, `hotfix` |
| `recipient` | Who it is for, when named |
| `deadline` | Parsed, timezone-aware UTC datetime |
| `deadline_expression` | The original phrasing, e.g. `by Friday EOD` |
| `due_condition` | `time`, `event_implicit`, `event_external` or `state` |
| `confidence` | 0.95 explicit + dated · 0.85 vague (`soon`) · 0.70 undated · 0.50 modal |
| `status` | Lifecycle state |

## 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](https://cogextai.com/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](https://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

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

## License

MIT © 2026 Yamin / THRYVIX
