quesen

# Quesen — Developer Portal

[![MCP compatible](https://img.shields.io/badge/MCP-2025--03--26-8B5CF6?labelColor=1F2937)](https://spec.modelcontextprotocol.io/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.Shxnque%2Fquesen-8B5CF6?labelColor=1F2937)](https://registry.modelcontextprotocol.io/v0/servers?search=quesen)
[![Smithery](https://img.shields.io/badge/Smithery-%40shinque03%2Fquesen-6366F1?labelColor=1F2937)](https://smithery.ai/server/@shinque03/quesen)
[![ASP version](https://img.shields.io/badge/ASP-1.0-06B6D4?labelColor=1F2937)](docs/api-reference.md)
[![Engine version](https://img.shields.io/badge/engine-1.10.0-16A34A?labelColor=1F2937)](https://web-production-3df26.up.railway.app/version)
[![PyPI](https://img.shields.io/pypi/v/quesen-sdk?label=pypi%20quesen-sdk&labelColor=1F2937&color=3775A9)](https://pypi.org/project/quesen-sdk/)
[![npm](https://img.shields.io/npm/v/quesen-sdk?label=npm%20quesen-sdk&labelColor=1F2937&color=CB3837)](https://www.npmjs.com/package/quesen-sdk)
[![Verified receipts](https://img.shields.io/badge/receipts-independently%20verifiable-16A34A?labelColor=1F2937)](verify/README.md)
[![License](https://img.shields.io/badge/license-MIT-6B7280?labelColor=1F2937)](./LICENSE)

> **Quesen** is the **deterministic decision-and-receipt core for agent actions** —
> a typed security context in, a `PASS / REVIEW / BLOCK / SKIP` verdict out, with
> machine reason codes and a receipt you can **re-run byte-for-byte and prove**.
> No model inference is in the scoring path, so the same input always yields the
> same verdict. It is built to sit **behind** injection detection, **on top of**
> agent identity, and to **bill per decision** (ASP/402).
>
> Unlike log-based governance layers whose audit trail is *their word, kept by
> them*, a Quesen receipt is **independently verifiable by the caller** —
> recomputable, and (engine signing enabled) Ed25519-signed. See
> [`docs/architecture-gap-closers.md`](docs/architecture-gap-closers.md) and
> client-side **enforcement + receipt verification** in `quesen-sdk` ≥ 0.5.0.
>
> This repository is the **public developer portal**. It contains **only**
> documentation, integration guides, examples, registry manifests, and
> reference links. **No engine source code lives here.** Quesen's engine
> implementation is sovereign, non-public infrastructure.

**Live production**

| Surface | URL |
| :--- | :--- |
| REST API | `https://web-production-3df26.up.railway.app` |
| MCP (Streamable HTTP) | `https://web-production-3df26.up.railway.app/mcp` |
| OpenAPI 3.1 | `https://web-production-3df26.up.railway.app/openapi.json` |
| Swagger UI | `https://web-production-3df26.up.railway.app/docs` |
| Health | `https://web-production-3df26.up.railway.app/health` |
| Version | `https://web-production-3df26.up.railway.app/version` |

---

## Quick start (30 seconds)

**Fastest path — no install, no signup, no card.** Self-serve a free sandbox key and run a
real deterministic decision against production. Full guide: [`docs/QUICKSTART.md`](docs/QUICKSTART.md)
· try it in the browser at [senueren.co.za/try](https://senueren.co.za/try).

```bash
# 1 · get a free sandbox key
curl -X POST https://web-production-3df26.up.railway.app/sandbox/keys

# 2 · evaluate an action (use the api_key from step 1)
curl -X POST https://web-production-3df26.up.railway.app/validate \
  -H "X-API-Key: sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{"domain_age_days": 1, "engagement_ratio": 0.95, "scam_keyword_count": 4}'
# -> {"decision":"SKIP","risk_score":1.0,"conflict_triggers":[...],"input_snapshot_hash":"..."}
```

### SDKs

> **Published.** The SDKs are live on PyPI and npm (`quesen-sdk` `0.5.0` / npm `0.5.0`;
> `quesen-langchain`, `quesen-crewai`, `quesen-autogen` `0.3.0`). The
> `base_url` + `X-API-Key` (including the sandbox key above) are identical across all SDKs.

### Python

```bash
pip install quesen-sdk   # PyPI: https://pypi.org/project/quesen-sdk/
```

```python
from quesen_sdk import QuesenClient

q = QuesenClient(base_url="https://web-production-3df26.up.railway.app",
                 api_key="YOUR_KEY")   # a sandbox key from /sandbox/keys works here

verdict = q.validate(domain_age_days=1, engagement_ratio=0.95, scam_keyword_count=4)
if verdict.decision == "SKIP":
    return  # respect the deterministic answer
```

### JavaScript / TypeScript

```bash
npm i quesen-sdk   # npm: https://www.npmjs.com/package/quesen-sdk
```

```ts
import { QuesenClient } from "quesen-sdk";

const q = new QuesenClient({
  baseUrl: "https://web-production-3df26.up.railway.app",
  apiKey: process.env.QUESEN_API_KEY,
});

const verdict = await q.validate({
  domain_age_days: 1,
  engagement_ratio: 0.95,
  scam_keyword_count: 4,
});
```

### Framework wrappers

| Framework | Package | Repository |
| --- | --- | --- |
| LangChain / LangGraph | `quesen-langchain` | [Shxnque/quesen-langchain](https://github.com/Shxnque/quesen-langchain) |
| CrewAI | `quesen-crewai` | [Shxnque/quesen-crewai](https://github.com/Shxnque/quesen-crewai) |
| AutoGen v0.4+ | `quesen-autogen` | [Shxnque/quesen-autogen](https://github.com/Shxnque/quesen-autogen) |
| Python (core) | `quesen-sdk` | [Shxnque/quesen-sdk-py](https://github.com/Shxnque/quesen-sdk-py) |
| JavaScript / TypeScript | `quesen-sdk` (npm) | [Shxnque/quesen-sdk-js](https://github.com/Shxnque/quesen-sdk-js) |

### MCP (Claude Desktop, Cursor, Windsurf, etc.)

Quesen exposes **five** MCP tools over the production endpoint. See
[`docs/mcp.md`](docs/mcp.md) for the client-config snippet.

---

## Why Quesen?

Autonomous agents make more decisions per second than any human oversight can
audit. When those decisions involve capital — launching a token, opening a
position, executing a trade, greenlighting a smart-contract deployment — the
marginal cost of a bad decision is fatal.

**Quesen answers exactly one question:**

> *Should the calling agent proceed with this action?*

Inputs are typed. Outputs are one of `PROCEED`, `REVIEW`, `SKIP`, always with a
`risk_score` in `[0.0, 1.0]`, a `confidence` in `[0.0, 1.0]`, and the exact
conflict rules that fired. **Same inputs → same output. Every time.** Every
response embeds `engine_version`, `weights`, and `thresholds`. Fully
reproducible. Fully auditable.

### What Quesen is not

- **Not an LLM wrapper.** No prompts. No probabilities.
- **Not a chatbot.** It is A2A infrastructure.
- **Not a KYC/identity system.** It scores risk, not identity.
- **Not chain-locked / framework-locked / LLM-locked.** Ecosystem-neutral by design.

---

## Documentation

- [Quickstart](docs/QUICKSTART.md) — first decision in under 10 minutes (free sandbox key).
- [Architecture overview](docs/architecture.md)
- [Integration guide](docs/integrations.md)
- [API reference](docs/api-reference.md)
- [MCP setup](docs/mcp.md)
- [Pricing tiers](docs/pricing.md)
- [FAQ](docs/faq.md)
- [Registry status](docs/registries.md)

### Independent verification

Published receipts are independently reproducible from this repo alone — no
hosted service or private engine required:

```bash
python3 verify/verify_receipts.py          # offline, stdlib-only
python3 verify/verify_receipts.py --live   # also cross-check the live engine
```

All six UCP #724 vectors show a byte-for-byte three-way match between the
published fixture, the public reference, and the live engine
([`verify/README.md`](verify/README.md), [`verify/three_way_match.json`](verify/three_way_match.json)).
That doc also states honestly where independent verification stops today (the
production ruleset `commit_sha` is not publicly resolvable; receipts are not yet
cryptographically issuer-signed).

The **egress/authority decision subset** — the part security integrators gate on —
is now independently *verdict*-replayable offline too, with **zero network**:

```bash
python3 evaluation/conformance/verify_conformance.py   # offline; recomputes decision+reasons+hash
```

Six cases (OWASP-agentic + LoopX prepared-Effect PASS/REVIEW/BLOCK) recompute
byte-for-byte from the public reference evaluator, plus a `prod-1→prod-2`
integrity-flip check — no signup, key, or hosted call
([`evaluation/conformance/README.md`](evaluation/conformance/README.md)).

### Tutorials

- [Moltbook post-guard](docs/tutorials/moltbook-post-guard.md) — deterministic pre-post safety gate for autonomous social agents.
- [OpenClaw MCP plugin](docs/tutorials/openclaw-plugin.md) — wiring Quesen as an MCP-native guardrail into OpenClaw-style agents.

---

## Live status

- Production: `https://web-production-3df26.up.railway.app`
- Health check: `GET /health` returns `{"status":"ok","engine_version":"1.10.0"}`
- Version snapshot: `GET /version` returns full engine + billing + on-chain flags (ASP/1.0)
- Uptime and version widget on [senueren.co.za/quesen](https://senueren.co.za/quesen)

---

## Registry presence

Quesen is discoverable via Model Context Protocol registries and the standard
agent-directory ecosystem. See [`docs/registries.md`](docs/registries.md) for
the current state of each submission. Manifests:

- [`smithery.yaml`](./smithery.yaml) — Smithery.ai (canonical)
- [`mcp.json`](./mcp.json) — MCP.so / generic MCP client (canonical)
- [`.well-known/ai-plugin.json`](./.well-known/ai-plugin.json) — OpenAI plugin
  manifest / `.well-known/ai-plugin.json` autodiscovery
- [`llms.txt`](./llms.txt) — machine-readable summary for LLM crawlers

---

## Contributing

This is a documentation-only repository. Engine PRs cannot be accepted here.
If you have integration-specific feedback, please [open an issue](https://github.com/Shxnque/quesen/issues) or read [`CONTRIBUTING.md`](CONTRIBUTING.md).

SDK contributions belong in the corresponding public SDK repository:

- Python: [Shxnque/quesen-sdk-py](https://github.com/Shxnque/quesen-sdk-py)
- JavaScript: [Shxnque/quesen-sdk-js](https://github.com/Shxnque/quesen-sdk-js)
- LangChain: [Shxnque/quesen-langchain](https://github.com/Shxnque/quesen-langchain)