# Platoon

**Percolation Labs' AI training suite for adding domain-specific agentic processes into [Percolate](https://github.com/Percolate-AI).**

Platoon provides the building blocks that let LLM agents do useful work in specific domains — commerce, analytics, content curation. It wraps standard techniques (forecasting, inventory math, optimization, customer segmentation) as callable tools behind clean provider interfaces, and connects external data sources (Shopify, RSS feeds, web search) into Percolate's schema and agentic system.

The goal: a business user asks a question in natural language, an agent discovers the right data and models, runs them, and returns an actionable answer. No spreadsheets, no dashboards, no SQL.

## Table of Contents

- [Install](#install)
- [Core Concepts](#core-concepts)
- [Modules](#modules)
  - [Learning Models](#learning-models) — 13 domains: forecasting, inventory, analytics, optimization, anomaly detection, basket analysis, cash flow, scheduling, and more
  - [Data Providers](#data-providers) — Shopify, pipeline infrastructure, commerce schema
  - [Feed Aggregator](#feed-aggregator) — 13 sources, scoring, HTML output
- [CLI](#cli)
- [Documentation Index](#documentation-index)
- [Development](#development)

## Install

```bash
# Core
uv pip install p8-platoon

# With learning models (forecasting, inventory, analytics)
uv pip install "p8-platoon[learning]"

# With optimization (LP/MIP via OR-Tools)
uv pip install "p8-platoon[optimization]"

# With web search enrichment
uv pip install "p8-platoon[search]"

# Everything
uv pip install "p8-platoon[learning,optimization,search]"
```

Development:

```bash
git clone <repo-url> && cd p8-platoon
uv pip install -e ".[learning,optimization,search]"
uv run python data/samples/generate.py  # synthetic test data
uv run python -m pytest tests/          # run tests
```

## Core Concepts

### Provider Pattern

Every capability in Platoon uses the same pattern: pluggable backends behind a common interface. Swap implementations without changing calling code.

```python
from platoon.learning.providers import get_provider

# Auto-selects best available backend
fc = get_provider("forecasting")       # statsforecast if installed, else builtin
inv = get_provider("inventory")         # stockpyl if installed, else builtin
opt = get_provider("optimization")      # OR-Tools

# Explicitly pick a backend
fc = get_provider("forecasting", backend="builtin")  # zero dependencies
```

### Percolate Integration

Platoon produces entities compatible with Percolate's data model:

- **Resources** — articles, products, data records with deterministic UUID5 IDs
- **Moments** — events, digests, analysis runs linked to resources
- **Agents** — JSON Schema definitions (description + structured attributes + tools) that discover and use Platoon's capabilities

All entities use Percolate's `uuid5(P8_NAMESPACE, "table:key:user_id")` scheme for idempotent upserts.

### Decision Layer (Planned)

The modules below are engines. The user-facing layer should be **decisions and alerts**: "what should I order this week?" not "run AutoETS with season_length=7". See [Decision Framework](platoon/learning/decision_framework.md) for the design.

## Modules

### Learning Models

Statistical and ML models that agents can invoke. 13 domains, each with pluggable backends.

| Domain | What it does | Backends |
|---|---|---|
| **Forecasting** | Predict demand per product per day | builtin (pure Python), statsforecast (Nixtla) |
| **Inventory** | EOQ, safety stock, reorder point, ABC, stockout risk | builtin (pure math), stockpyl |
| **Analytics** | RFM segmentation, customer LTV, cohort retention | scikit-learn + polars |
| **Optimization** | Linear/mixed-integer programming | OR-Tools (GLOP/CBC), PuLP (stub) |
| **Anomaly Detection** | Z-score + IQR rolling-window outlier detection | builtin, adtk (stub) |
| **Basket Analysis** | Co-occurrence association rules from order data | builtin, mlxtend (stub) |
| **Cash Flow** | Daily revenue/COGS/reorder cash projection | builtin |
| **Staff Scheduling** | Greedy cost-minimizing shift assignment | builtin, ortools (stub) |
| **Recommendations** | Collaborative filtering, hybrid models | implicit, lightfm (stub) |
| **Markdown/Clearance** | Discount cadence optimization | stub |
| **Promotion Simulator** | Lift/cannibalization/post-promo dip modeling | stub |
| **Lead Time Analysis** | Supplier reliability from receiving history | stub |
| **Seasonal Calendar** | Event-to-multiplier lookup table | stub |

```python
# Forecast demand
fc = get_provider("forecasting")
result = fc.forecast(sales_history, horizon=14, method="ets", season_length=7)

# Inventory optimization
inv = get_provider("inventory")
eoq = inv.eoq(demand=10000, ordering_cost=50, holding_cost=2)

# Anomaly detection
ad = get_provider("anomaly")
result = ad.detect(series, dates, method="zscore", window=30, threshold=2.5)

# Basket analysis
ba = get_provider("basket")
result = ba.analyze(transactions, min_support=0.001, min_confidence=0.01)

# Cash flow projection
cf = get_provider("cashflow")
result = cf.project(products, demand_by_product, inventory_state, horizon=14)

# Staff scheduling
sched = get_provider("scheduling", backend="builtin")
result = sched.schedule(demand_by_slot, staff, shift_hours=8)

# Customer segmentation
analytics = get_provider("analytics")
segments = analytics.rfm_segment(orders, n_clusters=4)

# Solve an allocation problem
opt = get_provider("optimization")
result = opt.solve(problem)
```

Full documentation: [Learning Models README](platoon/learning/Readme.md)

### Data Providers

Pipeline infrastructure for syncing external data sources into standard schema.

| Component | What it does |
|---|---|
| **DataProvider** | Abstract base for source integrations (Shopify, Stripe, etc.) |
| **Pipeline** | Orchestrates fetch → transform → sink with watermark-based incremental sync |
| **Commerce Schema** | Standard Pydantic models (Product, Order, Customer, Inventory) with prompt-like descriptions for agent discovery |
| **Shopify Provider** | Full GraphQL client with cursor pagination, bulk operations, rate limiting |

```python
from platoon.data import Pipeline
from platoon.data.providers.shopify import ShopifyProvider

provider = ShopifyProvider(shop="mystore.myshopify.com", token="shpat_xxx")
pipeline = Pipeline(state_file="sync_state.json")
pipeline.register("shopify", provider)

summary = await pipeline.run_all("tenant-1")
```

Full documentation: [Shopify Provider README](platoon/data/providers/shopify/Readme.md)

### Feed Aggregator

Content curation engine — 13 sources, profile-based scoring, web search enrichment. The original Platoon provider.

```bash
# Fetch, score, render HTML
platoon feed --profile default --open

# With web search enrichment
platoon feed --tavily-key tvly-...

# Export to Percolate entities
platoon export --profile default --output-dir ./export/
```

13 sources: Google News, Reddit, Hacker News, RSS/Atom, Flipboard, Trivia, arXiv, GitHub Trending, Lobsters, Papers With Code, Semantic Scholar, OpenAlex, HN Algolia.

## CLI

```bash
# Feed aggregation
platoon feed [--profile NAME] [--dry-run] [--open]
platoon export [--profile NAME] [--output-dir PATH]
platoon search "query" [--max-results N]

# Demand forecasting
platoon forecast --data daily_demand.csv --product PROD-1001 --compare
platoon forecast --data daily_demand.csv --top 5 --method ets --quiet

# Inventory optimization
platoon optimize --data products.csv --orders orders.csv --inventory inventory.csv

# Anomaly detection
platoon anomaly --data daily_demand.csv --product PROD-1004
platoon anomaly --data daily_demand.csv --product PROD-1004 --method iqr --threshold 1.5

# Basket analysis
platoon basket --orders orders.csv --min-support 0.001 --min-confidence 0.01 --max-rules 10

# Cash flow projection
platoon cashflow --data products.csv --demand daily_demand.csv --inventory inventory.csv --horizon 14

# Staff scheduling
platoon schedule --demand daily_demand.csv --staff staff.csv --shift-hours 8 --horizon 7

# Recommendations (planned)
platoon recommend --orders orders.csv --customer CUST-001

# Alerts (planned)
platoon alerts --severity critical
```

## Documentation Index

### Design & Architecture

| Document | Description |
|---|---|
| [Decision Framework](platoon/learning/decision_framework.md) | How modules compose into decisions and alerts. Alert schema, decision types, "Monday morning report" example. |
| [Commerce Manager Plan](.plans/commerce-manager) | Full system design — phased rollout, architecture, library choices, Shopify integration notes. |

### Module Guides

| Document | Description |
|---|---|
| [Learning Models](platoon/learning/Readme.md) | All learning modules — forecasting, inventory, analytics, optimization, recommendations. Benchmarks, provider architecture, library status. |
| [Forecasting Guide](platoon/learning/forecasting_guide.md) | End-to-end forecasting usage — method selection, accuracy evaluation, data format, CLI reference, replenishment example. |
| [Optimization Guide](platoon/learning/optimization.md) | How agents translate natural-language questions into LP/MIP problems. Expression parser, example session. |
| [Shopify Provider](platoon/data/providers/shopify/Readme.md) | GraphQL client, entity sync, rate limits, pipeline flow. |

### Data & Examples

| Document | Description |
|---|---|
| [Sample Datasets](data/samples/Readme.md) | Synthetic test data — 80 products, 5K customers, 130K orders, 731 days of demand/inventory, 20 staff. Generation script and schema mapping. |
| [MCP Test Cases](examples/mcp_test_cases.md) | 5 worked examples — forecasting, optimization, rush-order decisions, trend analysis, budget allocation. |
| [More Test Cases](examples/more-cases.md) | 4 worked examples — anomaly detection, basket analysis, cash flow projection, staff scheduling. |

## Development

```bash
# Run tests
uv run python -m pytest tests/ -v

# Generate sample data
uv run python data/samples/generate.py

# Current test count: 133 passing
#   29 data provider tests (schema, transform, pipeline, client)
#   72 learning tests (forecasting, inventory, analytics, optimization, anomaly, basket, cashflow, scheduling)
#   32 MCP tests (controllers, tool registration, agent schema)
#   + integration tests against sample data
```

### Project Structure

```
platoon/
├── cli.py                  # Main CLI entry point
├── data/
│   ├── provider.py         # DataProvider ABC + DataProviderResult
│   ├── pipeline.py         # Pipeline orchestration + SyncState
│   ├── schema.py           # Standard commerce Pydantic models
│   └── providers/
│       └── shopify/        # Shopify GraphQL client, provider, transformer
├── learning/
│   ├── providers.py        # ModelProvider ABC + registry
│   ├── forecasting.py      # Demand forecasting (builtin + statsforecast)
│   ├── inventory.py        # Inventory optimization (builtin + stockpyl)
│   ├── analytics.py        # RFM, LTV, cohort (sklearn + polars)
│   ├── optimization.py     # LP/MIP (OR-Tools + PuLP stub)
│   ├── anomaly.py          # Anomaly detection (builtin + adtk stub)
│   ├── basket.py           # Basket analysis (builtin + mlxtend stub)
│   ├── cashflow.py         # Cash flow projection (builtin)
│   ├── scheduling.py       # Staff scheduling (builtin + ortools stub)
│   ├── recommendations.py  # Collaborative filtering (stub)
│   ├── markdown.py         # Markdown/clearance optimization (stub)
│   ├── promotion.py        # Promotion simulator (stub)
│   ├── leadtime.py         # Lead time analysis (stub)
│   ├── seasonal.py         # Seasonal calendar (stub)
│   └── cli.py              # forecast, optimize, anomaly, basket, cashflow, schedule subcommands
├── sources/                # 13 feed source fetchers
├── providers.py            # FeedProvider (percolate entity output)
├── models.py               # P8Resource, P8Moment, deterministic IDs
├── scorer.py               # Keyword + engagement scoring
└── renderer.py             # HTML / JSON output
```

## License

MIT
