Metadata-Version: 2.5
Name: flieber
Version: 0.1.0
Summary: The flieber command: CLI and MCP server for Flieber commerce data (actual sales, adjusted sales, forecast).
Project-URL: Homepage, https://flieber.com
Author: Flieber
License: Proprietary
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.10
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13
Requires-Dist: starlette>=0.40
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: keyring
Requires-Dist: keyring>=25; extra == 'keyring'
Description-Content-Type: text/markdown

# flieber-cli

`flieber` is the command-line and agent interface to Flieber's commerce data. It gives developers, scripts and AI agents (Claude, Cursor, Lovable, custom agents) one stable, versioned way to read a tenant's:

- **actual sales**: what each channel recorded, per product × store;
- **adjusted sales**: actuals corrected for stockouts, outliers and price effects, used as the forecast input;
- **forecast**: expected demand per product × store, from today on (`meta.last_nonzero_forecast_period` is the latest period with a non-zero forecast; core-service exposes no horizon).

> **Status: v0 in design.** The architecture and contract v1 are [ADR-0001](docs/adr/0001-v0-architecture-and-contract-v1.md) (Accepted). The code arrives through the issues in the Linear project "Data Layer Product (Vibee) | Backend" (team Flieber AI - R&D, milestone M3). Only the `0.0.1` placeholder is published so far.

## Shape

One Python package: a shared core, and several surfaces built on it.

```
            ┌──────────────────── flieber (Python package) ────────────────────┐
            │  core: auth · GraphQL client · versioned tool contract · shaping  │
            └──────┬──────────────────────┬───────────────────────┬────────────┘
                   │                      │                       │
          CLI  `flieber …`      MCP (local)  `flieber mcp`   MCP (hosted)  `flieber mcp --http`
          humans & scripts      stdio, launched by           container behind a stable URL,
                                Claude / Cursor              used by the self-serve product
```

- **Core**
  - Authentication with a Flieber public-API key (`FLIEBER_API_KEY`, or the OS keyring or a 0600 config file, written by `flieber auth login`).
  - A client for core-service's public GraphQL API.
  - **The versioned tool contract:** one definition per capability. It drives both the CLI command and the MCP tool, so the two cannot drift (a ratchet test checks the parity, ADR-0001 §7).
  - Output shaping for humans (tables) and for LLMs (compact `{columns, rows}`, point caps, pagination).
- **CLI:** `flieber status`, `flieber listings`, `flieber products`, `flieber mapping`, `flieber sales`, `flieber adjusted`, `flieber forecast`, `flieber trends`. JSON output is available for scripts.
- **MCP:** the same capabilities as MCP tools, over stdio (local) or streamable HTTP (hosted, stateless). The hosted mode forwards the caller's own API key and stores nothing.

**Design rule:** customers bind to this contract, never to the raw GraphQL schema. The backend behind it may change; the contract changes only through versioning.

## Principles and how to contribute

- **What the project is,** and the rules no change may break (the three signals, least privilege, no secrets at rest, bounded cost and output, honest results): [`docs/00-invariants.md`](docs/00-invariants.md). It ranks above everything else.
- **How work is done** (proof before done, test-first, ports and adapters, one authoritative path per process): [`AGENTS.md`](AGENTS.md). It applies to humans and agents alike.
- **Decisions:** [`docs/adr/`](docs/adr/README.md).

## Tooling (v0)

- Python ≥ 3.12.
- Packaging with `uv` and `pyproject.toml`; installable as `uvx flieber …` / `pipx install flieber`.
- Tests with `pytest`, run as `uv run pytest` (ADR-0001 §8).

`flieber` is published on PyPI (the `0.0.1` placeholder, 2026-09-29, CI pipeline 2894945075). Releases, the version scheme and the changelog rules: [`docs/release.md`](docs/release.md).

## Development

```
uv sync                                        # Python ≥ 3.12, with the dev dependency group
uv run pytest                                  # tests never reach the network
uv run ruff check src tests scripts && uv run ruff format --check src tests scripts
uv run python -m flieber.contract.document --write   # after a contract change; review the diff
python scripts/pin_schema.py <core-service ref>      # re-pin core-service's schema
scripts/release_check.sh                       # build and verify dist/ exactly as CI does (docs/release.md)
uv run flieber --env qa ping                   # the proof run against QA (needs a QA key)
```

How work is done here, including what counts as proof, is in [`AGENTS.md`](AGENTS.md).

## Related

- **core-service:** the public GraphQL API at `/api/graphql`, and public-API keys with per-resource grants.
- **flieber-build-front:** the self-serve portal, which issues API keys and shows the MCP and CLI configuration.
- **ai-lab `tools/flieber_agent_tunnel`:** the existing `ask_flieber` MCP server. It is the reference for the streamable-HTTP MCP skeleton and the Clerk OAuth pieces.
