Skip to main content

Inventory Lens

Inventory Lens is an inventory-segmentation consultant for Analysts at third-party logistics (3PL) warehouses. Point it at your WMS exports and it profiles them with a deterministic engine, then guides you through Discovery towards a Segmentation Plan for slotting, Cycle Counts and Pick-Face Replenishment. Every number comes from the engine, never from the LLM (see ADR-0001).

It runs inside Claude Code as a plugin: you talk to Claude, and Claude uses the Inventory Lens engine to measure your data.

Status: version 0.1.0. You can run Discovery end to end and run ABC (by units picked, Hits, cube moved or value), XYZ, VED, FSN and HML, with Combined Segmentations such as ABC-XYZ, at the Segmentation Level you choose. The other Segmentation Methods are still to come.

Install

Do this once. You need three things: Claude Code, uv, and your WMS exports.

1. Install Claude Code

Claude Code needs a Claude subscription or Anthropic Console account. Follow the Claude Code setup guide, or in a terminal:

System Open Run
macOS Terminal (press Cmd+Space, type "Terminal") curl -fsSL https://claude.ai/install.sh | bash
Linux Your terminal curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell (Start menu, type "PowerShell") irm https://claude.ai/install.ps1 | iex

Close the terminal and open it again, then check with claude --version.

2. Install uv

uv is a small tool that fetches the right version of Python and the engine the first time Inventory Lens starts. You never set up Python yourself.

System Run in the terminal
macOS or Linux curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close the terminal and open it again, then check with uvx --version. More ways to install uv.

3. Add the plugin

Open a terminal in the folder where you keep your work for this organization (the Workspace will be created inside it), start Claude Code with claude, and type these two lines, one at a time:

/plugin marketplace add ducdeb3rry/inventory-lens
/plugin install inventory-lens@inventory-lens

Then quit Claude Code (type /exit) and start it again with claude. The first start takes a minute: uv downloads the engine and its parts. Type /mcp to check that inventory-lens is listed as connected.

To update later, run claude plugin marketplace update inventory-lens and then claude plugin update inventory-lens@inventory-lens in the terminal, and restart Claude Code.

The one-time notice

Before it profiles anything, Inventory Lens shows you this notice, and it does not go on until you agree:

Inventory Lens runs its calculations locally, but every tool result it returns is sent to the LLM used by your MCP host (for example, Claude Code). That includes Data Source file names, column names, inferred types, row counts, date ranges and missing-value rates, and in later steps item codes, Client names, descriptions and class results. Raw files are never uploaded as a whole. Every tool result is also appended to llm_log.jsonl in this Workspace, so you can review exactly what was sent to the LLM. Acknowledge this notice before any Data Source is profiled.

In plain words: your files stay on your computer and the engine reads them there. What the engine reports about them (names, counts, dates, and later item codes, Client names and results) is passed to the LLM so it can explain it to you, and a copy of everything passed is kept in llm_log.jsonl in your Workspace so you can read it. Check that your organization allows this before you agree, especially for Client names and item descriptions.

To acknowledge it, read it when Claude shows it and answer that you agree. Claude records that once in workspace.yaml; you are not asked again for that Workspace. If you say no, Discovery stops and nothing is profiled.

Your first Discovery

Have your WMS exports ready: an Item Master (one row per Item) and the Movements (receipts, picks, moves, adjustments, returns), as CSV, Parquet or Excel files (.xlsx, .xlsm). Stock Snapshots and Locations help but are optional. Headers in English and Vietnamese are recognized.

Start Claude Code in your work folder and say, for example: "Start Inventory Lens Discovery." Claude follows these steps and stops to ask you at each decision. You can talk in your own language; everything written to the Workspace is in English.

  1. Create the Workspace. Claude asks where it should live; the default is an inventory-lens/ folder in the folder you started in. Everything Discovery produces is saved there, so you can stop at any point and carry on in a later session: Claude picks up from the first step not yet done.
  2. Acknowledge the notice (above).
  3. Register your Data Sources. Give Claude the paths of your files. Each CSV or Parquet file is one Data Source; each sheet of an Excel workbook is its own Data Source, named <workbook>.<sheet>. Each is stored with a fingerprint, so Inventory Lens can tell later if a file changed.
  4. Profiling. Claude profiles each Data Source and tells you what it found: the number of rows, each column's inferred type, date ranges and missing-value rates, and which columns are mostly empty.
  5. Field Mapping. Claude proposes which column supplies each field of the Canonical Model (Item Master, Movements, and optionally Stock Snapshots and Locations), including which of your WMS movement codes mean receipt, pick, internal move, adjustment or return. The Site (warehouse, distribution center or store) of a Movement is never taken from a bin or slot column: a bin or slot is a Location. The engine checks the mapping and shows the evidence: how many values fit each field, how many dates parse (and when a date could be read two ways, Claude asks which), how many Movements have a mapped Movement Type, how many Movements and Items are found in the Item Master, and which item codes more than one Client uses (an Item is its Client together with its item code, so those stay separate Items). Confirmation: you confirm the mapping or correct it. Only picks count as demand by default, so check the movement codes carefully. Once it is confirmed, Claude also reports the data issues found in the Movements: returns, negative quantities, outliers, internal moves, adjustments, and New and Obsolete Items.
  6. Interview. Claude asks only what Profiling could not answer, one Interview Topic at a time: your objectives, your operating model, the Target KPIs that matter to you (captured, never computed), your Client service commitments and your preferences. Where the data already answers a topic, Claude tells you what it inferred and you confirm it. You can say a topic does not apply to you. Your Client service commitments become Criticality Rules (such as "all of MEDILINK's Medical Items are Vital"); Claude proposes a VED class for each Item no rule covers, from its description and category, and you confirm or correct every one. Discovery cannot be completed while any topic is uncovered.
  7. Discrepancies. If something you said conflicts with what the data measures (for example three years of history stated against 153 days in the files), Claude shows you the Discrepancy. The measured value is the one used. You check it (a file may be missing) and say how it is resolved; if data is missing you register it and profile again.
  8. Confirm the Data Landscape. Claude shows the Data Landscape Summary as measured: each Data Source and mapped part, the Movements, picks, dates, history, Clients, Items and the data issues, and each Discrepancy with its resolution. You confirm it, and Discovery is then complete. No Segmentation Plan is drafted before this.
  9. Feasibility and the Discovery Report. Claude gives a Feasibility Verdict for ABC, XYZ, VED, FSN and HML (Feasible, Feasible with Caveats, or Infeasible with the reason), measured from the data only, and writes the Discovery Report to discovery_report.md: the Data Landscape, data quality, every Discrepancy and its resolution, each Feasibility Verdict, the recommended methods and the Defaults version. The engine writes every number in it; anything the LLM adds to explain it sits in sections headed "Narrative".
  10. Draft and confirm the Segmentation Plan. Claude drafts a Segmentation Plan in which every choice has its reasoning and source: the methods, their Cut-offs and Look-back Windows, the Segmentation Level, the Combined Segmentations, a Data Treatment for each kind of data issue, and the New and Obsolete Lifecycle Classes. It also names the Defaults version used, the Data Sources' fingerprints, and any method left out and who left it out. Ask for changes in your own words (the Segmentation Level, ABC's Basis, Cut-offs, Look-back Windows, XYZ's Demand Period, which Combined Segmentations to produce, which Movement Types count as demand), or edit segmentation_plan.yaml yourself; every change is checked and one that cannot be used is rejected with the reason. You can Override an Infeasible method by giving your reason; it is recorded in the plan. Nothing is run until you confirm the plan, and a plan edited after you confirmed it must be confirmed again.
  11. Run it, when you ask. A Segmentation Run happens only when you explicitly ask for one ("run the segmentation"). Claude Code also asks your permission before every run unless you allowed the tool yourself. Claude reports the Class Summary: for each method the Items per class, for each Combined Segmentation its grid, and how many Items are New or Obsolete. If your Data Sources changed since the plan was drafted, the plan is a Stale Plan and the run is refused until you profile again and draft a new plan.
  12. Class Policies. Every run also gives every class and Combined Segmentation cell, and the New and Obsolete Lifecycle Classes, a Class Policy from the Policy Library in the Defaults: its Storage Zone, Cycle Count frequency, Pick Face, Pick-Face Replenishment and review of slow and non-moving stock, each value with its source. Claude may add Advice for your organization; it is always labelled as Advice and never contains a policy number.

Each Segmentation Run is kept in its own folder under runs/ in the Workspace, together with the plan it used, so you can ask Claude about past runs at any time.

The Segmentation Level sets what is ranked together: Items warehouse-wide (the default, with the Class Summary broken down by Client), Items within each Client, or Stocking Points (each Item at each Site, which needs Movements that name their Site).

The starting values come from the versioned Defaults; each one cites a source or says it is a convention (see the research).

Inventory Lens supports up to about 50,000 Items and 10,000,000 Movements. A Data Source with more rows than that is still profiled, and the profile reports its size and the limit. Items are identified by their Client together with their item code, so they are counted once the Field Mapping says which columns hold those; more Items than the limit are reported the same way.

Every tool result the engine returns is appended to llm_log.jsonl in the Workspace, so you can check exactly what was sent to the LLM.

Where the files land

Everything is in your Workspace folder (by default inventory-lens/ in the folder you started Claude Code in):

  • discovery_report.md: the Discovery Report.
  • segmentation_plan.yaml: the Segmentation Plan, which you can edit.
  • runs/<NNNN>/classes.xlsx and classes.csv: each Item's class in every method, from a Segmentation Run. class_summary.yaml and class_policies.md sit beside them.
  • llm_log.jsonl: everything the engine sent to the LLM.

Workspace layout

File Holds
workspace.yaml Format version, whether the notice was acknowledged, and whether Discovery is complete
data_sources.yaml Registered Data Sources with their fingerprints
profiles/<name>.yaml The latest Profiling result for each Data Source
proposals/field_mapping.yaml The last validated Field Mapping, waiting for your Confirmation
proposals/data_landscape.yaml The last Data Landscape Summary, waiting for your Confirmation
data_landscape.yaml The confirmed Field Mapping, with its evidence and the fingerprints of the Data Sources it was checked against, and the Data Landscape Summary you confirmed
interview.yaml The Interview: each Interview Topic's status with its answers or reason, the Target KPIs, the Criticality Rules, each Item's VED label or proposal with its source and status, and every Discrepancy with its statement, measured value and resolution
feasibility.yaml The latest Feasibility Verdicts, with each Method Requirement checked
discovery_report.md The Discovery Report, as last rendered
discovery_report_narrative.yaml The LLM's narrative for the Discovery Report, by section, kept apart from what the engine computes
segmentation_plan.yaml The Segmentation Plan: draft or confirmed, every choice with its reasoning and source (the Defaults, or "Analyst" for a value you changed), any override of an Infeasible verdict with your reason, and for each method left out, who left it out (your reason for one you left out is kept whatever its verdict becomes)
runs/<NNNN>/ One Segmentation Run: classes.csv, classes.xlsx (each Item's class in every method and joint class in every Combined Segmentation), class_summary.yaml (with each method's Feasibility Verdict at run time and any override, and a grid for each Combined Segmentation), a frozen plan.yaml and run.yaml (with the overrides it ran under and the Policy Library version), class_policies.yaml (every Class Policy with its sources, as the Policy Library gave it), class_policies.md (the Class Policies rendered, with any Advice in its own labelled sections) and advice.yaml (the LLM's Advice, kept apart)
llm_log.jsonl Every tool response sent to the LLM

Maintaining

The gate

uv sync
uv run mypy
uv run pytest -m "not packaging"   # Seam 1: the engine's MCP tools, in process
uv run pytest -m packaging         # builds the wheel and launches the plugin's config through uvx

Tests drive the engine's MCP tools through an in-process MCP client and assert only on tool results and Workspace files (Seam 1). They run against Synthetic Organizations, generated deterministically from a seed in tests/synthetic/. CI runs the gate on every pull request.

Headless eval

Seam 2 runs the real plugin headless against the Synthetic Organizations with a simulated Analyst. It spends Claude and Gemini usage, so it runs only on demand: the Headless Interview eval workflow in GitHub Actions (workflow_dispatch), or uv run python tests/run_headless_eval.py --help locally. It needs the repository secrets INVENTORY_LENS_EVAL_CLAUDE_OAUTH_TOKEN and INVENTORY_LENS_EVAL_GEMINI_API_KEY.

Releasing

The plugin launches the engine with uvx --from inventory-lens==<version> inventory-lens-mcp, so the PyPI package and the plugin share one version, kept the same in pyproject.toml, uv.lock, .claude-plugin/plugin.json and the pin in plugin.json (python3 scripts/check_release_version.py checks them). The packaging tests build the wheel and point the pin at it, so they pass before a version is published.

  1. Change the version in all four places in one commit (uv lock updates uv.lock), and merge it to main.
  2. Push the tag v<version> on that commit straight away: until the release publishes, the default branch's plugin pins a version PyPI does not have yet, and the engine cannot start from it.
  3. The Release workflow (.github/workflows/release.yml) runs on that tag only: it checks the tag against the version, runs the gate, builds, publishes to PyPI through Trusted Publishing (no stored token) and creates the GitHub Release.

If a release fails before PyPI has the version (check https://pypi.org/project/inventory-lens/), fix main, delete the tag (git push --delete origin v<version> and git tag -d v<version>) and tag the fixed main commit again with the same version. If PyPI already has the version, it can never be uploaded again: bump the version and release that.

The parts only a person can do (the PyPI account and its pending Trusted Publisher, the pypi GitHub environment, and pushing the tag) are in an interactive walkthrough that checks what it can and never asks for a secret:

scripts/release-wizard.sh          # walk through every step
scripts/release-wizard.sh --check  # only report the automatic checks

To try the plugin from a checkout before a version is published, build the wheel (uv build --wheel) and serve it with UV_FIND_LINKS=dist claude --plugin-dir ..

Vocabulary is defined in CONTEXT.md and decisions in docs/adr/.

License

MIT

Metadata

Release files for inventory-lens 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for inventory-lens 0.1.0
File Size Uploaded Provenance Actions
inventory_lens-0.1.0.tar.gz 321.1 kB With provenance Details for inventory_lens-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for inventory-lens 0.1.0
File Interpreter ABI Platform Actions
inventory_lens-0.1.0-py3-none-any.whl Python 3 none any Details for inventory_lens-0.1.0-py3-none-any.whl

Total release size: 440.9 kB

Release files / inventory_lens-0.1.0.tar.gz

Download URL inventory_lens-0.1.0.tar.gz
Size 321.1 kB
Tags Source
SHA-256 checksum
How to use checksums
4a905173b8466a70612accf57a2ef7a1d4614a10cb1b4e97b4ea4762104063df
BLAKE2b-256 checksum
How to use checksums
1736fdeeb9dd7d48be07ff7f168cdb0fb758e3af945012cfac3357db2df16c37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / inventory_lens-0.1.0-py3-none-any.whl

Download URL inventory_lens-0.1.0-py3-none-any.whl
Size 119.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3aa42f528500164267aad8e96dc672576f3ebe1e03c5eda9628c2de92a7e45c5
BLAKE2b-256 checksum
How to use checksums
366c26021cd97a770a85bcc3935402bf532f601958af5bee9a44fe493bd7f910
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for inventory-lens 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for inventory_lens-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page