Metadata-Version: 2.5
Name: cometric
Version: 0.4.0
Summary: Commercial Intelligence Engine: model, simulate, and optimize the economics of service engagements.
Project-URL: Homepage, https://github.com/mfbaig35r/cometric
Project-URL: Repository, https://github.com/mfbaig35r/cometric
Project-URL: Issues, https://github.com/mfbaig35r/cometric/issues
Project-URL: Changelog, https://github.com/mfbaig35r/cometric/blob/main/CHANGELOG.md
Author: Fahad Baig
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: commercial,consulting,economics,legal,managed-services,mcp,pricing,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.9
Requires-Dist: pyyaml>=6.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.10; extra == 'mcp'
Description-Content-Type: text/markdown

# Cometric

[![CI](https://github.com/mfbaig35r/cometric/actions/workflows/ci.yml/badge.svg)](https://github.com/mfbaig35r/cometric/actions/workflows/ci.yml)

**Commercial Intelligence Engine.** Cometric models the commercial arrangements behind service engagements, simulates their economics month by month, and searches for structures that balance profitability, risk, and client value.

1. **Model.** Arrangements are compositions, not a single "pricing model": billing bases, rate schedules, allowances, minimums, adjustments, delivery costs, and capacity, each typed and validated.
2. **Simulate.** A deterministic decimal engine computes contractual fees, costs by margin layer, contribution, client effective unit price, capacity use, and who absorbs each deviation from plan.
3. **Optimize.** A grid search over the parameters you declare returns the trade-off frontier. Nothing is ranked unless you supply an objective, and every recommendation is marked for human review.

It is built for any service relationship priced through a composite arrangement: consulting, outsourcing, managed services, and alternative legal services. Sector knowledge ships as data-only packs.

## Guarantees

- **No model arithmetic.** Every amount is computed by decimal code. Floating-point input is rejected.
- **Reproducible.** Each result carries a SHA-256 fingerprint of its canonical inputs, engine version, and policies.
- **Traceable.** Every fee line records its evaluation step, formula, quantity, and contract version.
- **Explicit policy.** Cost layering, capacity ceilings, recognition rules, and risk tolerances are inputs. Missing economic policy is an error, never a silent default.
- **Labeled knowledge.** Pack concepts and claims carry evidence classes. Inference and proposals are always labeled as such.

## Install

```bash
pip install "cometric[mcp]"           # or: uv pip install "cometric[mcp]"
uv sync --all-extras                  # from a checkout
```

[![PyPI](https://img.shields.io/pypi/v/cometric)](https://pypi.org/project/cometric/)

Python 3.11 or later.

## Quickstart

```bash
cometric validate src/cometric/examples/spec_example.json
cometric calculate src/cometric/examples/case_a.json --scenario base --cost-policy reference
cometric explain src/cometric/examples/spec_example.json --period 2027-01
cometric break-even src/cometric/examples/case_b.json --driver contracts --scenario base --cost-policy reference
cometric floor src/cometric/examples/case_b.json --cost-policy reference --target-margin 0.20
cometric template base_plus_overage
cometric template phased_fixed_fee --pack consulting
cometric template tiered_units_annual_minimum --pack alsp
cometric reconcile engagement.json --scenarios actual-quantities.json --actuals actuals.json --cost-policy reference --summary-only
cometric lookup PM-023
```

```python
import json

import cometric

case = json.load(open("src/cometric/examples/case_a.json"))
result = cometric.calculate_periods(case["engagement"], case["scenarios"][1], "reference", detail="periods")
print(result["term"]["contribution_margin"], result["input_fingerprint"])
```

## MCP server

Cometric ships a read-only, stateless MCP server: 19 tools (start with `quickstart`), schema and template discovery, resources for the glossary, schemas, concept schemes, rules, coverage, templates, and worked examples, and six guided prompts.

```bash
cometric mcp                                   # stdio
COMETRIC_ALLOWED_ROOT=/path/to/models cometric mcp   # stdio, may read input files under that root
cometric mcp --transport http --port 8765      # stateless streamable HTTP at POST /mcp
```

Claude Code:

```bash
claude mcp add cometric -- uvx --from "cometric[mcp]" cometric mcp
```

The HTTP transport keeps no session state, answers `GET /mcp` with 405, keeps DNS-rebinding protection on (set `COMETRIC_ALLOWED_HOSTS` for your hostname), and checks a bearer token when `COMETRIC_MCP_TOKEN` is set.

## Concepts

| Concept | Meaning |
|---|---|
| Engagement | Parties, units, services, effective-dated arrangement versions, delivery plan |
| Fee component | One charge computed by one method: fixed recurring, time, dedicated resource, unit output, weighted unit output, allowance plus overage, fixed project, outcome adjustment (gain-share, success fee, percent of outcome) |
| Realization | Contractual fee against hours worked at a standard rate card, with write-down and effective billing rate |
| Accumulation period | Allowances, minimums, tiers, and capacity accumulate over a declared period independent of the monthly grain |
| Evaluation order | Resolve, measure, consume allowances, price, collar, discount, minimum, performance, cap |
| Cost policy | Maps each cost category to exactly one margin layer; `reference` is shipped and must be named |
| Scenario | Immutable, origin-labeled assumptions spread to months by exact allocation |
| Derived risk | Who absorbs a deviation: provider contribution versus client unit price |
| Dominance | A candidate is dominated when another is at least as good on every metric and better on one |

## Packs

Packs are YAML only, with no executable code. `base` holds domain-neutral commercial knowledge: billing bases, 34 pricing models, 61 levers, 16 commercial dimensions, 49 metrics and indicators, cost categories, compatibility and reasoning rules, selection heuristics, mechanisms, and negotiation exchanges. `alsp` extends it for alternative legal services with service categories, unit templates, provider types, regulatory review rules, sector prevalence overlays, and evidence. `consulting` extends it for advisory work with realization and staffing concepts, outcome-fee review rules, and five templates: role-based time and materials, capped time and materials, phased fixed fee, hours-drawdown retainer, and fixed fee plus success fee.

```bash
cometric packs
cometric validate-pack alsp
cometric validate-pack consulting
```

## Development

```bash
uv sync --all-extras
uv run pytest
uv run ruff check src tests scripts && uv run ruff format --check src tests scripts
uv run python scripts/build_fixtures.py   # regenerate casebook fixtures
```

The specification is `docs/COMETRIC_SPEC_v0.3.md` (normative for 0.1.0). Implementation status is in `docs/STATUS.md`; worked commercial patterns (tiered minimums, transition credits, partial billing, cost from hours, early termination) are in `docs/PATTERNS.md`; reconciling a real engagement is described in `docs/RECONCILIATION.md`.

## License

Apache License 2.0. See `LICENSE`.
