# Thing Event System (TES)

> The system of record for things that evolve over time. Every product, asset, and agent carries its full history, AI enrichment, and intelligence — so your systems can understand, reason, and act.

TES is a GraphQL API by Pentatonic that models the real world as Things that evolve over time. Things can be physical products, digital assets, agents, or any entity with a lifecycle. Every state change is recorded as an immutable event, enriched by AI, and projected into current state — creating a unified system where history, understanding, and intelligence compound on the same event spine.

## API

- Endpoint: `POST /api/graphql`
- Auth: OAuth 2.0 Bearer Token (`Authorization: Bearer <token>`)
- Required header: `X-Client-Id: <client-id>`
- Format: GraphQL over HTTPS (JSON request/response)

## Core Entities

### Things
Physical items tracked through 26 lifecycle stages. Each thing has a holder (who has it), a location (where it is), and optionally a product (what it is). AI enrichment automatically identifies brand, model, condition, and market value from uploaded images.

### Holders
People or organisations that hold things: customers, warehouses, stores, carriers, processors, manufacturers. Every custody transfer is recorded as an immutable event.

### Locations
Physical places: warehouses, stores, processing centres, distribution centres. Things move between locations, and every move is tracked.

### Products
The product catalog. Things are instances of products. Products have brand, category, SKU, tags, and features.

### Shipments
Logistics tracking with multi-provider support, tracking numbers, status history, cost, and delivery confirmation.

### Payments
Financial transactions linked to things: prepay, COD, refund. Status lifecycle from pending through processing to completed.

### Events
The immutable audit log. Every mutation emits an event. Events have entityId, entityType, eventType, timestamp, and payload.

## Key Queries

- `things(limit, offset)` — list things with pagination
- `thing(id)` — get a thing with all enriched fields (vision, pricing, valuation)
- `holders(limit, offset)` — list holders
- `holder(id)` — get holder details
- `locations(limit, offset)` — list locations
- `location(id)` — get location details
- `products(limit, offset)` — list products
- `product(id)` — get product details
- `shipments(filter, limit, offset)` — list shipments
- `payments(filter, limit, offset)` — list payments
- `events(filter, limit, offset)` — list events
- `searchThings(input)` — vector similarity search across things
- `searchProducts(input)` — vector similarity search across products
- `thingsCountByStage(stages)` — analytics by lifecycle stage
- `eventStats` — event counts by type and time period
- `edgeHistory(entityId)` — relationship change history

## Key Mutations

- `createThing(input)` — create a thing (physical or digital)
- `updateThing(id, input)` — update thing attributes
- `addThingStatus(id, input)` — advance lifecycle stage
- `transferThing(id, input)` — transfer custody to new holder
- `changeThingLocation(id, input)` — move to new location
- `uploadThingImage(id, input)` — upload image (triggers AI enrichment)
- `createHolder(input)` — create a holder
- `createLocation(input)` — create a location
- `createProduct(input)` — create a product
- `createShipment(input)` — create a shipment
- `createPayment(input)` — create a payment

## Lifecycle Stages

Things progress through these stages:
manufactured → sourced → in_stock → in_transit → delivered → sold → in_use → captured → identified → valued → returned → received → processing → inspecting → refurbishing → repairing → processed → certified → listed → resold → recycled → donated → disposed

Problem states: issue, rejected, lost

## AI Enrichment Pipeline

When an image is uploaded to a thing, TES automatically runs:
1. Vision Analysis — identifies brand, model, colorway, category, condition
2. Market Pricing — returns price range (low/mid/high) with confidence
3. Valuation — estimates resale value
4. Name Generation — auto-generates name from vision data
5. Text Embedding — 1024-dim vector for semantic search
6. Product Matching — auto-links to catalog product or creates new

## Vector Search

Search things and products by natural language query, similar item ID, or image. Uses BGE-M3 embeddings (1024 dimensions) with cosine similarity ranking.

```graphql
query {
  searchThings(input: { query: "vintage leather jacket", min_score: 0.7, limit: 10 }) {
    items { score thing { id name vision { brand category condition { grade } } } }
  }
}
```

## SDKs

### JavaScript / TypeScript
```bash
npm install @pentatonic/ai-agent-sdk
```

```javascript
import { TESClient } from '@pentatonic/ai-agent-sdk';

const tes = new TESClient({
  apiKey: 'tes_...',
  clientId: 'your-client-id',
});

// Auto-wrap any LLM client for observability
const ai = tes.wrap(new OpenAI());
```

### Python
```bash
pip install pentatonic-agent-events
```

```python
from pentatonic_agent_events import TESClient

tes = TESClient(
    api_key="tes_...",
    client_id="your-client-id",
)

# Auto-wrap any LLM client
ai = tes.wrap(openai_client)
```

Both SDKs provide LLM observability (token usage, tool calls, conversation tracking) and direct TES API access.

- npm: https://www.npmjs.com/package/@pentatonic/ai-agent-sdk
- PyPI: https://pypi.org/project/pentatonic-agent-events/
- GitHub: https://github.com/Pentatonic-Ltd/ai-agent-sdk

## Integration

### MCP (Model Context Protocol)
TES provides MCP tools for AI assistants: list_things, get_thing, create_thing, update_thing, add_thing_status, transfer_ownership, change_location, search_things, list_holders.

```json
{
  "mcpServers": {
    "tes": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "https://tes.pentatonic.com/sse"],
      "env": { "TES_API_TOKEN": "tes_..." }
    }
  }
}
```

### OAuth 2.0
- Authorization Code Flow with PKCE (user-facing apps)
- Client Credentials Flow (server-to-server)
- Token format: `tes_<client>_<random>`

### Webhooks
HMAC-SHA256 signed event delivery to your endpoints.

## Links

- Website: https://thingeventsystem.ai
- Documentation: https://thingeventsystem.ai/docs
- GraphQL Playground: https://thingeventsystem.ai/graphql
- E2E Demo: https://thingeventsystem.ai/e2e
- Status: https://thingeventsystem.ai/status
- npm (JS/TS): https://www.npmjs.com/package/@pentatonic/ai-agent-sdk
- PyPI (Python): https://pypi.org/project/pentatonic-agent-events/
- GitHub: https://github.com/Pentatonic-Ltd/ai-agent-sdk
- SDK docs: https://thingeventsystem.ai/sdk
- Discord: https://discord.gg/QZJe9FtkWj
- Parent company: https://pentatonic.com