# procurement-graph

A dependency graph of strategic sourcing artifacts and analyses, exposed as an MCP server.

This is an open specification I publish through Canonical Agency. It generalizes patterns from procurement and spend-intelligence engagements at two enterprises under NDA.

## What it models

The strategic sourcing process is usually drawn as a linear set of phases. I find that framing brittle. Phases describe *when* work happens; they do not describe *what depends on what*. The same spend cube feeds the diagnostic, the category strategy, and the ongoing performance dashboard. The same supplier scorecard depends on baseline metrics captured during onboarding. Treating these as a graph (nodes plus edges) makes it possible to ask the questions that actually matter on an engagement:

- What deliverables are blocked by missing inputs?
- If raw spend changes, what gets invalidated?
- Given my entity-profile data, which analyses can I run today?
- What is the build order to produce a category strategy?

Phases (0 through 6) remain in the spec as a navigational frame. They are not the structural spine.

## Phase model

Seven phases, zero through six, anchoring the program from opening diagnostic through ongoing performance management.

```
Phase 0  Opportunity Assessment & Business Case
Phase 1  Spend Analysis & Category Segmentation
Phase 2  Supply Market Research
Phase 3  Strategy Development
Phase 4  Sourcing Execution (RFx + Negotiation)
Phase 5  Implementation & Supplier Transition
Phase 6  Performance Management & Benefits Tracking
```

## Layer model

Every node lives in one of five layers. Layers describe *what kind of work* a node is, independent of which phase it belongs to.

```
Layer 1  Truth and facts          (raw data, supplier master, contracts)
Layer 2  Analytical assets        (spend cube, should-cost, risk scores)
Layer 3  Decision artifacts       (category strategy, negotiation strategy)
Layer 4  Execution artifacts      (RFx packages, contracts, transition plans)
Layer 5  Proof and control        (benefits tracking, scorecards, compliance)
```

## Tools (v0.4)

Navigation and catalog:

| Tool | Purpose |
|---|---|
| `list_phases()` | Seven phases with one-line purpose |
| `get_phase(number)` | Full phase spec (purpose, included activities, layer focus) |
| `list_analyses(primary_phase?, layer?, feasibility?)` | Layer 2 analyses, filterable by feasibility with PO-line data |
| `get_analysis(slug)` | Full analysis spec (firms, inputs, method, outputs, watch-outs) |
| `list_deliverables(primary_phase?, layer?)` | Layer 3-5 deliverables |
| `get_deliverable(slug)` | Full deliverable spec (purpose, audience, components, dependencies) |
| `list_horizontal_artifacts()` | Cross-phase artifacts (governance, RAID, benefits tracker) |
| `get_engagement_context()` | Shared fictional engagement (TechnoFlex PSA resin) that anchors all examples |
| `list_artifact_examples()` | Filled-in artifact examples, each tied to a parent node slug |
| `get_artifact_example(slug)` | Fetch a filled-in TechnoFlex example for a given parent node slug |

Graph traversal:

| Tool | Purpose |
|---|---|
| `get_dependencies(slug)` | Direct upstream nodes for a given node |
| `get_dependents(slug)` | Direct downstream nodes for a given node |
| `what_breaks_if(slug)` | Transitive closure of downstream nodes (impact analysis) |
| `build_order(target_slug)` | Topological sort of every upstream node plus the target |
| `feasible_now()` | Nodes flagged HIGH feasibility against PO-line + entity-profile data |
| `data_gap_analysis()` | Nodes blocked by MISSING inputs, ranked by transitive impact |

## Install (local / editable)

```bash
cd /Users/fbaig/Projects/procurement-graph
uv sync
uv run procurement-graph
```

## Validate the content corpus

`procurement-graph validate` runs the integrity checks the test suite enforces (edge consistency, acyclicity, example linkage, phase continuity) as a standalone CLI. Useful for content editors to verify their work before committing.

```bash
uv run procurement-graph validate
```

## Claude Desktop config

```json
{
  "mcpServers": {
    "procurement-graph": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/fbaig/Projects/procurement-graph",
        "run",
        "procurement-graph"
      ]
    }
  }
}
```

## Repository layout

```
content/
├── phases/         seven phase descriptions
├── analyses/       Layer 2 analyses from the procurement analytics catalog
├── deliverables/   Layer 3-5 deliverables from the phase-by-phase taxonomy
├── horizontal/     cross-phase artifacts (governance, RAID, benefits tracker)
├── engagement/     shared fictional engagement (TechnoFlex PSA resin)
└── examples/       15 filled-in artifact examples anchored to the TechnoFlex engagement

src/procurement_graph/
├── __main__.py     entrypoint dispatching to MCP server or validate CLI
├── server.py       FastMCP app and tool registrations (16 tools)
├── loaders.py      cached file readers
├── parsing.py      YAML frontmatter and markdown body parsing
├── models.py       pydantic node, phase, and example models
├── graph.py        dependency-graph traversal (BFS, topo sort, feasibility)
└── validate.py     standalone content-integrity checks
```

The methodology content lives in `content/` as markdown with YAML frontmatter, so the source of truth is editable without touching the server code.

## License

Apache-2.0.