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.
- 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. - Acknowledge the notice (above).
- 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. - 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.
- 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.
- 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.
- 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.
- 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.
- 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". - 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.yamlyourself; 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. - 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.
- 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.xlsxandclasses.csv: each Item's class in every method, from a Segmentation Run.class_summary.yamlandclass_policies.mdsit 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.
- Change the version in all four places in one commit (
uv lockupdatesuv.lock), and merge it tomain. - 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. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.