Metadata-Version: 2.4
Name: stigmem-node
Version: 0.9.0a4
Summary: Stigmem reference node — single-host production implementation
Author-email: Eidetic Labs <oss@eidetic-labs.ai>
License: Apache-2.0
Requires-Python: >=3.11
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: canonicaljson>=2.0
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: packaging>=24
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.11
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: starlette>=1.0.1
Requires-Dist: uvicorn[standard]>=0.34
Provides-Extra: conformance
Requires-Dist: pgvector>=0.2.0; extra == 'conformance'
Requires-Dist: psycopg2-binary>=2.9; extra == 'conformance'
Requires-Dist: pytest>=8.0; extra == 'conformance'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: embed-openai
Requires-Dist: openai>=1.0; extra == 'embed-openai'
Provides-Extra: encryption
Provides-Extra: libsql
Requires-Dist: libsql-experimental>=0.0.1; extra == 'libsql'
Provides-Extra: observability
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.24; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'observability'
Requires-Dist: prometheus-client>=0.20; extra == 'observability'
Provides-Extra: postgres
Requires-Dist: pgvector>=0.2.0; extra == 'postgres'
Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
Provides-Extra: sqlcipher
Requires-Dist: sqlcipher3>=0.5.0; extra == 'sqlcipher'
Provides-Extra: sqlite-vec
Requires-Dist: sqlite-vec>=0.1.0; extra == 'sqlite-vec'
Description-Content-Type: text/markdown

# Stigmem Reference Node

Single-host reference implementation of the Stigmem protocol. The modular protocol
specs live under [`../spec/specs/`](../spec/specs/), with the generated protocol
composition at [`../spec/PROTOCOL.md`](../spec/PROTOCOL.md).

## Quick start

```bash
# install
pip install .

# run (auth disabled, local db)
stigmem-node

# run with auth
STIGMEM_AUTH_REQUIRED=true STIGMEM_DB_PATH=./data/stigmem.db stigmem-node
```

Default port: **8765**. Override with `STIGMEM_PORT`.

## Configuration

All settings via environment variables (prefix `STIGMEM_`):

| Variable              | Default                  | Description |
|-----------------------|--------------------------|-------------|
| `STIGMEM_DB_PATH`      | `stigmem.db`              | SQLite file path |
| `STIGMEM_HOST`         | `0.0.0.0`                | Bind host |
| `STIGMEM_PORT`         | `8765`                   | Bind port |
| `STIGMEM_NODE_URL`     | `http://localhost:8765`  | Canonical URL for `/.well-known/stigmem` |
| `STIGMEM_AUTH_REQUIRED`| `false`                  | Enforce API-key auth |
| `STIGMEM_LOG_LEVEL`    | `info`                   | uvicorn log level |

## CORS

The Stigmem node ships with CORS disabled by default. Enable it only for the
deployment shape you operate.

### Local development (any localhost port)

```bash
STIGMEM_CORS_DEV_LOCALHOST=1
```

Accepts any `Origin` matching
`^https?://(localhost|127\.0\.0\.1)(:\d+)?$`. Use this when the UI and API run
on separate, dynamically chosen localhost ports.

### Production with a known UI origin

```bash
STIGMEM_CORS_ALLOWED_ORIGINS=https://stigmem-ui.example.com
```

### Production with multiple UI origins

```bash
STIGMEM_CORS_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com
```

### Self-managed regex (advanced)

```bash
STIGMEM_CORS_ALLOWED_ORIGIN_REGEX=^https://[a-z0-9-]+\.example\.com$
```

### Credentials

`STIGMEM_CORS_ALLOW_CREDENTIALS` defaults to `true` and controls whether
browsers may send cookies or `Authorization` headers cross-origin. Set it to
`false` only when the deployment does not use credentialed browser requests.

### Security note

Do not combine `STIGMEM_CORS_DEV_LOCALHOST=1` with a production deployment. The
dev-localhost regex is intentionally permissive and must only run on
maintainer-controlled machines.

## API

| Route | Description |
|-------|-------------|
| `POST /v1/facts` | Assert a fact (`Spec-03-HTTP-API`) |
| `GET /v1/facts` | Query facts (`Spec-03-HTTP-API`) |
| `GET /.well-known/stigmem` | Node metadata (`Spec-03-HTTP-API`) |
| `GET /healthz` | Health check |
| `GET /docs` | OpenAPI UI |

## Running tests

```bash
cd stigmem/node
pip install ".[dev]"
pytest
```

## Docker

```bash
docker build -t stigmem-node .
docker run -p 8765:8765 -v $(pwd)/data:/data stigmem-node
```
