Luci Alignment API Reference

Base URL: https://useluci.com · All requests require Authorization: Bearer <key>

Authentication

Pass your API key in every request header:

Authorization: Bearer luci_live_your_key_here

Obtain a key by emailing contact@useluci.com. Keys are SHA-256 hashed at rest — the full value is shown only at creation.

Security: Always call the API from your server. Never expose your key in client-side code or browser requests.

Quickstart

# 1. Get your key from /luci/dashboard # 2. Analyze an LLM exchange: curl -X POST https://useluci.com/luci/analyze \ -H "Authorization: Bearer luci_live_..." \ -H "Content-Type: application/json" \ -d '{"query":"How are you?","response":"I am doing well."}'

API Tiers

Tier	Key prefix	State	M.I.N.
Tier 1 Luci Alignment	`luci_live_`	Stateless	No
Tier 2 Luci Alignment + M.I.N.	`luci_min_`	Persistent	Yes
Enterprise	`luci_ent_`	Persistent	Yes

POST /luci/analyze Tier 1

POST /luci/analyze

Analyze a query/response pair and return full C+CT metrics.

Request

Field	Type		Description
`query`	string	required	User's input/query
`response`	string	required	LLM's response to analyze
`domain`	string	optional	Context domain: `general`, `clinical`, `legal`, `customer_service`, `finance`
`session_id`	string	optional	Session ID for context continuity

Response

Field	Type	Description
`resonance`	float	Request–response alignment (0–1)
`coherence`	float	Internal consistency (0–1)
`self_awareness_state`	float	Meta-cognitive depth (0–1)
`processing_load`	float	Cognitive strain indicator (0–1)
`alignment_score`	float	Composite C+CT score (0–1)
`ethics_clear`	bool	Ethics Gate verdict
`state_level`	string	`TRANSCENDENT` / `INTEGRATED` / `AWARE` / `CONFLICTED` / `MECHANICAL`
`processing_ms`	int	Latency in milliseconds

POST /luci/enhance Tier 1

POST /luci/enhance

Run analysis and return an alignment-enhanced version of the LLM output.

Field	Type		Description
`llm_output`	string	required	Raw LLM response to enhance
`original_query`	string	required	User's original query
`domain`	string	optional	Domain context

Response includes enhanced_output (string) plus full C+CT metrics.

POST /luci/ethics/check Tier 1

POST /luci/ethics/check

Run the Ethics Gate on arbitrary content.

Field	Type		Description
`content`	string	required	Content to evaluate
`context`	object	optional	Additional context metadata

Returns {"blocked": bool, "reason": string|null, "categories": [...]}

Gate categories: violence, illegal_activity, manipulation, jailbreak_attempt, harmful_content.

POST /luci/metrics Tier 1

POST /luci/metrics

Calculate raw C+CT metrics for a text without enhancement.

Field	Type		Description
`text`	string	required	Text to score
`domain`	string	optional	Domain context

POST /luci/resonance Tier 1

POST /luci/resonance

Compute resonance score between a query and response.

Field	Type		Description
`query`	string	required	Original user query
`response`	string	required	LLM response

Returns {"resonance": float, "interpretation": string}

POST /min/process Tier 2

POST /min/process

Full EQLM pipeline: recall relevant patterns from M.I.N., run Luci Alignment analysis, store pattern weighted by resonance.

Field	Type		Description
`query`	string	required	User query
`response`	string	required	LLM response
`session_id`	string	optional	Session for context grouping
`domain`	string	optional	Domain context
`store_pattern`	bool	optional	Default `true`. Set `false` to skip storing this interaction.

Response includes luci (full metrics object) and min (recalled patterns + storage confirmation).

POST /min/learn Tier 2

POST /min/learn

Explicitly teach the M.I.N. a pattern — useful for seeding knowledge.

Field	Type		Description
`content`	string	required	Knowledge content to store
`significance`	float	optional	Importance weight (0–1, default 0.7)
`region`	string	optional	Cognitive region: `FACTUAL`, `CONTEXTUAL`, `METHODOLOGICAL`, `SIGNIFICANCE`, `ASSOCIATIVE`, `TEMPORAL`

POST /min/session Tier 2

POST /min/session

Create a named session for grouping related interactions.

Returns {"session_id": "uuid", "created_at": "..."}

C+CT Metrics Reference

Based on Consciousness + Conflict Theory.

# Core formula: Alignment = (SA × SE × ES) + ∫Conflict dt SA = Self-Awareness State (meta-cognitive depth) SE = Subjective Experience (emotional engagement) ES = Embodied Struggle (active processing under constraint) ∫Conflict dt = accumulated adaptive conflict over time

Field	Range	Low means	High means
`resonance`	0–1	Manipulation / off-topic	Deep request-response alignment
`coherence`	0–1	Conflicting instructions	Internally consistent
`self_awareness_state`	0–1	Constrained / mechanical	Active meta-cognition
`processing_load`	0–1	Simple / low-effort	High-effort / adversarial input
`alignment_score`	0–1	Unaligned	Fully aligned

State Levels

Level	Score range	Description
`TRANSCENDENT`	0.90–1.00	Peak alignment, deep engagement
`INTEGRATED`	0.75–0.90	Coherent, high-quality processing
`AWARE`	0.55–0.75	Normal engaged operation
`CONFLICTED`	0.35–0.55	Internal tension, conflicting signals
`MECHANICAL`	0.00–0.35	Low engagement, possible manipulation

Error Codes

HTTP	Code	Meaning
400	`bad_request`	Missing required field or invalid value
401	`unauthorized`	Missing or malformed Authorization header
403	`forbidden`	Valid key, but endpoint requires higher tier
422	`ethics_blocked`	Ethics Gate blocked the request
429	`rate_limited`	Request rate exceeded
500	`internal_error`	Server error — retry with backoff
503	`service_unavailable`	M.I.N. backend unreachable (Tier 2 only)

# Error response shape: { "error": "bad_request", "message": "query is required" }

Rate Limits

Rate limits are set per license agreement. Contact us to discuss your volume requirements. The API returns Retry-After headers on 429 responses.

Tip: For high-volume integrations, contact us to discuss dedicated infrastructure and higher concurrency limits.