Metadata-Version: 2.5
Name: open-commerce-agent
Version: 0.0.1.dev0
Summary: Provider-agnostic reference commerce agent — a fork of anthropics/commerce-agents that runs on any OpenAI-compatible chat-completions endpoint (OpenRouter, Chutes, LiteLLM, vLLM, self-hosted).
Project-URL: Repository, https://github.com/ORO-AI/open-commerce-agent
Project-URL: Upstream, https://github.com/anthropics/commerce-agents
Author: ORO AI
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.91
Requires-Dist: openai>=1.50
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.5; extra == 'dev'
Provides-Extra: vendored
Description-Content-Type: text/markdown

# open-commerce-agent

Provider-agnostic reference commerce agent. A fork of
[`anthropics/commerce-agents`](https://github.com/anthropics/commerce-agents)
that runs on **any OpenAI Chat Completions–compatible endpoint** —
OpenRouter, Chutes, LiteLLM, vLLM, Ollama, LM Studio, self-hosted.

Apache-2.0. Vendored subset of Anthropic's original at a pinned commit
(see `UPSTREAM.md`); wrapped with a streaming Anthropic Messages ⇄
OpenAI Chat Completions translator so the upstream `ShoppingAgent`
orchestrator's tool-loop, gates, and prompt work unchanged against
non-Anthropic backends.

> **Status: Alpha / WIP.** Runtime shim, request + response translation,
> and end-to-end wiring against Anthropic (via OpenRouter) and OSS
> models (via OpenRouter) are proven working. Public-facing polish
> (installer, docs, PyPI package) still landing.

## Why

Anthropic's reference implementation binds you to Claude via their
Messages API + Claude Agent SDK. That's the right call for the primary
use case, but leaves everyone running OSS models — Kimi K3, DeepSeek
V3.2, Qwen 3.5, GLM 5.2, Gemma, Mistral — to either roll their own
commerce agent from scratch or accept vendor lock-in.

This fork keeps everything upstream ships (tools, prompts, safety
gates, presentation, memory, executor) and swaps only the model call —
so you can run the exact same agent on the exact same tools against
whichever model wins your capability matrix this month.

## Install

Wheel install (once we're on PyPI — the workflow is scaffolded):

```bash
pip install open-commerce-agent
```

The wheel bundles the vendored Anthropic subset as top-level
`commerce_common` / `shopping_agent` / `shopping_agent_runtime` /
`merchant_agent` / `merchant_agent_runtime` packages, so no
post-install step is required. Both the shopping and merchant
orchestrators use the same `OpenAIChatCompatClient` — one shim
covers both agent families.

Source install (contributors, or before PyPI publish):

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
bash scripts/install.sh   # installs the vendored subset editable
```

Editable-install needs the shell script because the vendored code
sits under `vendored/upstream/` at development time; the script
`pip install -e`s the three sibling packages so changes there flow
without a reinstall. The wheel-install path doesn't need it — hatch
bundles them into the wheel.

## Quickstart

Copy `configs/openrouter.env.example` → `.env`, fill in a key + model,
then run the smoke against a built-in mock catalog:

```bash
source .env      # OPENAI_BASE_URL, OPENAI_API_KEY, MODEL
oca smoke        # or: python examples/smoke.py
```

You should see the model call `search` → `add_to_cart` and end with a
one-line assistant summary. That validates your provider+model combo.

To wire your own catalog, implement the `StorefrontBackend` protocol
against your data (`examples/mock_backend.py` is a minimal reference,
[`docs/adding-a-backend.md`](docs/adding-a-backend.md) is the full
guide), then:

```python
from open_commerce_agent import build_client_from_env
from shopping_agent.config import ShoppingAgentConfig
from shopping_agent_runtime.orchestrator import ShoppingAgent

client, model = build_client_from_env()
agent = ShoppingAgent(
    backend=YourStorefrontBackend(),
    client=client,
    config=ShoppingAgentConfig(model=model),
)
# ... call agent.stream_turn(messages, session, state) per turn
```

See `examples/smoke.py` for the full session loop.

## Capability matrix

**Community-maintained — file a PR against this section when you add
or update a row.** Pass rate is from an internal reference task set (a
public benchmark harness is a follow-up).

_Section stub — real matrix landed after the first CI round of live
smokes; see `docs/capability-matrix.md` for the current view._

| Model | Provider | Tool-calling | Streaming | Notes |
|---|---|---|---|---|
| `anthropic/claude-sonnet-4-5` | OpenRouter | ✅ | ✅ | Reference — matches direct Anthropic API behaviour. |
| `moonshotai/kimi-k2` | OpenRouter | ✅ | ✅ | Native tool_calls. Notably good product-selection prose. |
| … | … | … | … | *file a PR* |

## Provider recipes

See `configs/` for ready-to-copy environment configurations for each
supported provider:

- `configs/openrouter.env.example` — OpenRouter (Claude, Kimi, DeepSeek,
  Qwen, GLM, Gemma, all via one endpoint)
- `configs/litellm.env.example` — self-hosted LiteLLM proxy
- `configs/vllm.env.example` — self-hosted vLLM with a chat template
- `configs/openai.env.example` — hosted OpenAI (fallback)

None is a "default" — the point of this package is you pick.

## What upstream did well that we kept

- `StorefrontBackend` — clean abstract interface with one method per
  domain operation. Any catalog can implement it in under a day.
- Provenance gates that block hallucinated product IDs and cart writes
  on unseen items. Safety-relevant, keep it.
- Skills-as-prompt-modules pattern — the five `SKILL.md` files under
  `vendored/upstream/shopping-agent/skills/` are what makes the agent
  feel domain-competent. Keep them; contribute skill additions upstream
  where possible.
- The full turn loop + presentation-tool streaming + memory extraction.

## What we changed (all in the wrapper layer, none in the vendored code)

- `runtime_openai_shim/` — the translation shim. See `CHANGES.md` for
  details.
- No default model, no cache_control fakery, no merchant agent, no
  Claude Agent SDK path.

## License

- `vendored/upstream/*` — Apache-2.0, Anthropic PBC (see the vendored
  `LICENSE`).
- `src/open_commerce_agent/*` — Apache-2.0, ORO AI.

Neither Anthropic nor Claude endorse or maintain this fork. This is an
independent adaptation for the OpenAI-compat wire protocol.

## Migrating from `anthropics/commerce-agents`

Already running the upstream reference and want to switch providers?
The diff is roughly six lines. See
[`docs/migrating-from-upstream.md`](docs/migrating-from-upstream.md).

## Observability

`OpenAIChatCompatClient(..., on_request=…, on_response=…)` — plug in
logging / tracing / cost accounting per model call without patching
the shim. See [`docs/observability.md`](docs/observability.md).

## Reference

- [`docs/glossary.md`](docs/glossary.md) — terms used across the
  codebase and docs (StorefrontBackend, provenance gate, orchestrator,
  shim, presentation vs data, session vs state, …).
- [`docs/architecture.md`](docs/architecture.md) — box diagram and
  the shim's place in the request path.
- [`docs/troubleshooting.md`](docs/troubleshooting.md) — symptom →
  fix for the failure modes we've actually seen (empty responses,
  cart stays empty, tool-calls dropped, provider quirks).
- [`docs/adr/`](docs/adr/) — architecture decision records.

## Related

- Upstream: https://github.com/anthropics/commerce-agents
- Upstream tracking + sync: [`UPSTREAM.md`](UPSTREAM.md)
- Local changes: [`CHANGES.md`](CHANGES.md)
