Clausula is a local-first, deterministic investment decision system. It combines versioned ledgers, market and portfolio state, policy-as-code, planning, decision memory, research evidence, recommendations and material-attention tracking without making an LLM the system of record.
- Financial calculations use deterministic Python services and
Decimal. - Historical facts are append-only and retain source provenance.
- As-of queries distinguish
effective_at,known_at, andrecorded_atso look-ahead is explicit. - Capital state, policy boundaries, evidence, recommendations, decisions, execution constraints and reviews remain distinct concepts.
- CLI, workspace, HTTP, MCP, plugin and agent surfaces project the same deterministic application state rather than owning financial truth.
- Version 0.x does not place brokerage orders autonomously.
Requires Python 3.12 or newer.
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[research]"
clausula capability list
clausula system check
clausula account create DemoInstitution "Paper Account"
# Preferred local owner: starts the loopback daemon and Capital Cockpit.
clausula-daemonclausula-workspace remains a compatibility entry point and routes through the same daemon path. The daemon owns local write serialization, server-side principal permissions and request-bound confirmation state. Its generated daemon-auth.json is sensitive ephemeral runtime state and must not be committed.
The Capital Cockpit is decision-first: as_of and known_as_of remain visible, and the read model composes valuation completeness, allocation/concentration, reserve/deployable cash, policy headroom, execution constraints, plans, attention, evidence pressure, recommendations, decisions and review lineage. Anonymous workspace projection is read-only; capability invocation requires a daemon-issued local bearer principal.
| Layer | Responsibility |
|---|---|
clausula/domain |
immutable domain types and temporal contracts |
clausula/application |
deterministic use cases and repository ports |
clausula/analytics |
portfolio, policy, planning, performance and accounting calculations |
clausula/adapters |
SQLite, backup, audit, migrations, market/accounting projections and MCP |
clausula/capabilities |
permissioned capability registry shared by integration surfaces |
clausula/plugins |
plugin manifest, discovery, host-policy authorization and supervised subprocess execution |
clausula/api, clausula/ui, cli.py, sdk.py |
daemon, local HTTP/workspace, CLI and Python projections |
Research ingestion supports local text/Markdown/HTML/PDF plus stateless web capture with source maps and provenance. Market provider contracts include raw-payload capture and explicit return semantics; Tencent CN/HK daily data has a live acceptance subset, while broader real-provider and private-corpus evidence remains a release-gate task.
See docs/project/STATUS.md for implementation status and docs/project/LOCAL_ACCEPTANCE.md for the remaining release gates.
python -m pytest -q
python -m compileall -q clausula tests
python -m build
git diff --checkClausula is local-first. Runtime financial data, databases, backups, raw private research, agent state, tool configuration and credentials do not belong in this repository. Loopback bearer authentication is a local integration boundary, not an internet-facing TLS or multi-tenant security contract. Plugin host policy and the Linux bwrap runner provide separate authorization and containment layers; real-host containment still requires local acceptance evidence. See SECURITY.md.
There is intentionally no stable release tag yet. Repository protection (#6) and the accounting v12 migration (#21) are complete. The first tagged release is now gated principally on host-runtime acceptance (#23) and real-data/private-corpus/target-machine acceptance (#34).
MIT. See LICENSE.