Metadata-Version: 2.5
Name: open-commerce-agent
Version: 0.1.0a2
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: hypothesis>=6.100; 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)
designed for **OpenAI Chat Completions–compatible endpoints** —
OpenRouter, Chutes, LiteLLM, vLLM, Ollama, LM Studio, self-hosted.
(Only OpenRouter has been validated end-to-end so far — see the
capability matrix.)

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.** Live on PyPI as `open-commerce-agent`. Runtime
> shim, request + response translation, both shopping + merchant
> orchestrators bundled, and end-to-end wiring against Claude
> (via OpenRouter) and OSS models (via OpenRouter) are proven
> working. First real user validation and capability-matrix rows
> for non-OpenRouter providers still to come.

## Why

The upstream reference provides Messages API, Claude Agent SDK, and
Managed Agents runtimes for Claude. This independent fork vendors
the shopping and merchant Messages API subset and adds a client shim
for OpenAI Chat Completions–compatible endpoints — so the same
tools, prompts, gates, and orchestrators can run against models
reached through OpenRouter, Chutes, LiteLLM, vLLM, or a
self-hosted server.

This fork retains a pinned, attributed subset of upstream's shopping
and merchant tools, prompts, gates, memory, and Messages API
orchestrators, and translates model-client calls. It does not include
the upstream Agent SDK, Managed Agents, examples, or other omitted
components.

## Install

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

(`--pre` needed while the current version is an alpha —
`0.1.0a1`. Drop the flag once v0.1.0 final lands.)

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 | ✅ | ✅ | OpenRouter route used as the current cross-model smoke baseline; tool-calling and streaming observed. |
| `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 `SKILL.md` files under
  `vendored/upstream/shopping-agent/skills/` and
  `vendored/upstream/merchant-agent/skills/` are what make the agents
  feel domain-competent. Publish fork-specific skill additions here
  and track upstream changes in `UPSTREAM.md`.
- 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 Agent SDK or Managed
  Agents runtimes.

The shopping and merchant core, skills, and Messages API runtimes
are vendored; Agent SDK and Managed Agents runtimes are not.

## 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/agents.md`](docs/agents.md) — shopping vs merchant agent
  families, backend contracts, wiring shape.
- [`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/versioning.md`](docs/versioning.md) — SemVer policy,
  vendored SHA sync cadence, release checklist.
- [`docs/testing.md`](docs/testing.md) — test tier map for
  contributors.
- [`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)
