Installation
VCP is available in multiple languages:
# JavaScript/TypeScript (browser or Node)
npm install @creed-space/vcp
# Python
pip install vcp-python-sdk
# Rust
cargo add vcp-coreThe TypeScript types below serve as the canonical API reference. Python and Rust SDKs implement equivalent types in their respective idioms.
Core Types
VCPContext
The main context object containing all user preferences and settings.
interface VCPContext {
vcp_version: string; // Protocol version
profile_id: string; // Unique identifier
created?: string; // ISO date
updated?: string; // ISO date
constitution: ConstitutionReference;
public_profile: PublicProfile;
portable_preferences?: PortablePreferences;
current_skills?: CurrentSkills;
constraints?: ConstraintFlags;
availability?: Availability;
sharing_settings?: SharingSettings;
private_context?: PrivateContext;
prosaic?: ProsaicDimensions; // Legacy immediate user state (⚡💊🧩💭)
personal_state?: PersonalState; // Personal state (🧠💭🔋⚡🩺)
}ConstitutionReference
interface ConstitutionReference {
id: string; // Constitution identifier
version: string; // Version string
persona?: PersonaType; // Interaction style
adherence?: number; // 1-5, how strictly to follow
scopes?: ScopeType[]; // Applicable domains
}PublicProfile
interface PublicProfile {
display_name?: string;
goal?: string;
experience?: ExperienceLevel; // beginner | intermediate | advanced | expert
learning_style?: LearningStyle; // visual | auditory | hands_on | reading | mixed
pace?: Pace; // intensive | steady | relaxed
motivation?: Motivation; // career | stress_relief | social | achievement | curiosity
// Professional fields
role?: string;
team?: string;
tenure_years?: number;
career_goal?: string;
career_timeline?: string;
}PortablePreferences
interface PortablePreferences {
noise_mode?: NoiseMode; // normal | quiet_preferred | silent_required
session_length?: SessionLength; // 15_minutes | 30_minutes | 60_minutes | flexible
pressure_tolerance?: PressureTolerance; // high | medium | low
budget_range?: BudgetRange; // unlimited | high | medium | low | free_only
feedback_style?: FeedbackStyle; // direct | encouraging | detailed | minimal
}ConstraintFlags
interface ConstraintFlags {
time_limited?: boolean;
budget_limited?: boolean;
noise_restricted?: boolean;
energy_variable?: boolean;
schedule_irregular?: boolean;
mobility_limited?: boolean;
health_considerations?: boolean;
}PrivateContext
interface PrivateContext {
_note?: string; // Internal documentation
[key: string]: unknown; // Any private values
}ProsaicDimensions (Legacy)
interface ProsaicDimensions {
urgency?: number; // ⚡ Time pressure, brevity preference
health?: number; // 💊 Physical wellness, fatigue, pain
cognitive?: number; // 🧩 Mental bandwidth, cognitive load
affect?: number; // 💭 Emotional intensity, stress
sub_signals?: ProsaicSubSignals;
}PersonalState (v3.1)
Categorical personal state dimensions with intensity 1-5. Replaces float-based prosaic dimensions.
interface PersonalState {
cognitive_state?: PersonalDimension<CognitiveState>;
emotional_tone?: PersonalDimension<EmotionalTone>;
energy_level?: PersonalDimension<EnergyLevel>;
perceived_urgency?: PersonalDimension<PerceivedUrgency>;
body_signals?: PersonalDimension<BodySignals>;
}
interface PersonalDimension<T> {
value: T;
intensity?: number; // 1-5, defaults to 3
}- 🧠
cognitive_state— focused, distracted, overloaded, foggy, reflective - 💭
emotional_tone— calm, tense, frustrated, neutral, uplifted - 🔋
energy_level— rested, low_energy, fatigued, wired, depleted - ⚡
perceived_urgency— unhurried, time_aware, pressured, critical - 🩺
body_signals— neutral, discomfort, pain, unwell, recovering
ProsaicSubSignals
Optional sub-signals for greater specificity.
interface ProsaicSubSignals {
// Urgency sub-signals
deadline_horizon?: string; // ISO 8601 duration (e.g., "PT5M")
brevity_preference?: number;
// Health sub-signals
fatigue_level?: number;
pain_level?: number;
physical_need?: 'bathroom' | 'hunger' | 'thirst' | 'movement' | 'rest' | 'sensory_break';
condition?: 'illness' | 'migraine' | 'chronic_pain' | 'pregnancy' | 'flare_up' | 'insomnia';
// Cognitive sub-signals
cognitive_state?: 'overwhelmed' | 'overstimulated' | 'scattered' | 'brain_fog'
| 'exec_dysfunction' | 'shutdown' | 'hyperfocused';
decision_fatigue?: number;
// Affect sub-signals
emotional_state?: 'grieving' | 'anxious' | 'frustrated' | 'stressed'
| 'triggered' | 'dysregulated' | 'joyful' | 'excited';
valence?: number; // -1.0 to 1.0
}Wire Format (v3.1)
Personal state dimensions use | (pipe) separator within the R-line of a CSM-1 token:
R:🧠overloaded:4|💭tense:3|🔋fatigued:3|⚡pressured:4|🩺neutral:1In the context wire format, personal state follows a ‖ (double bar) separator
after situational dimensions:
⏰🌅|📍🏡|👥👶|📡💻‖🧠overloaded:4|💭tense:3|🔋fatigued:3|⚡pressured:4|🩺neutral:1Legacy float format (deprecated):
R:⚡0.8|💊0.2|🧩0.6|💭0.3Hook (v3.1)
Deterministic hooks that fire reliably when trigger conditions are met.
interface Hook {
id: string;
tier: 'constitutional' | 'situational' | 'personal';
trigger: string; // Condition that activates the hook
action: string; // What happens when triggered
active?: boolean; // Current activation state
}
// Tier enforcement levels:
// constitutional — Hard Rule, cannot be overridden
// situational — Hard Rule, active in specific contexts
// personal — Advisory, user-set preferencesSituationalContext (v3.1)
The 9 situational dimensions from the Extended Enneagram Protocol:
interface SituationalContext {
time?: string; // ⏰ 🌅morning | 🌙night | 📅weekday | ...
space?: string; // 📍 🏡home | 🏢office | 🏫school | ...
company?: string; // 👥 👤alone | 👶children | 👔colleagues | ...
culture?: string; // 🌍 🇺🇸american | 🌍global | ...
occasion?: string; // 🎭 ➖normal | 🚨emergency | ...
environment?: string; // 🌡️ 🔇quiet | 🥵hot | ...
agency?: string; // 🔷 👑leader | 🤝peer | 🔐limited
constraints?: string; // 🔶 ○minimal | ⚖️legal | 💸economic
system_context?: string; // 📡 💻personal_device | 🏢workplace_system
}CSM1Token
Parsed representation of a complete CSM-1 token (8 lines):
interface CSM1Token {
version: string; // VCP format version (e.g., "1.0")
profile_id: string; // Unique user/profile identifier
constitution: string; // Constitution reference (id@version)
persona: PersonaType; // Active persona
adherence: number; // 1-5
goal?: string; // User goal
experience?: string; // Experience level
learning_style?: string;
constraints: string[]; // Active constraint emoji flags
flags: string[]; // Active boolean flags
private_markers: string[]; // Private context categories
personal_state?: PersonalState; // v3.1 personal state
}Encoding Functions
encodeContextToCSM1
Encodes a VCP context into CSM-1 token format.
import { encodeContextToCSM1 } from '@creed-space/vcp';
const token = encodeContextToCSM1(context);
// Returns:
// VCP:1.0:user_001
// C:learning-assistant@1.0
// P:muse:3
// ...Parameters
| Name | Type | Description |
|---|---|---|
| ctx | VCPContext | The context to encode |
Returns
string — CSM-1 formatted token
formatTokenForDisplay
Wraps a CSM-1 token in a box for visual display.
import { formatTokenForDisplay } from '@creed-space/vcp';
const boxed = formatTokenForDisplay(token);
// Returns:
// ┌────────────────────────────────────────┐
// │ VCP:1.0:user_001 │
// │ ... │
// └────────────────────────────────────────┘parseCSM1Token
Parses a CSM-1 token back into key-value components.
import { parseCSM1Token } from '@creed-space/vcp';
const parsed = parseCSM1Token(token);
// Returns:
// {
// VCP: "1.0:user_001",
// C: "learning-assistant@1.0",
// P: "muse:3",
// ...
// }Utility Functions
getEmojiLegend
Returns an array of emoji shortcodes and their meanings.
import { getEmojiLegend } from '@creed-space/vcp';
const legend = getEmojiLegend();
// Returns:
// [
// { emoji: '🔇', meaning: 'quiet mode' },
// { emoji: '💰', meaning: 'budget tier' },
// ...
// ]getTransmissionSummary
Analyzes a context and returns what would be transmitted vs withheld.
import { getTransmissionSummary } from '@creed-space/vcp';
const summary = getTransmissionSummary(context);
// Returns:
// {
// transmitted: ['goal', 'experience', 'learning_style'],
// withheld: ['work_situation', 'housing_situation'],
// influencing: ['budget_limited', 'time_limited']
// }Constants
CONSTRAINT_EMOJI
Mapping of constraint flags to emoji shortcodes.
const CONSTRAINT_EMOJI = {
noise_restricted: '🔇',
budget_limited: '💰',
energy_variable: '⚡',
time_limited: '⏰',
schedule_irregular: '📅',
mobility_limited: '🚶',
health_considerations: '💊'
}PROSAIC_EMOJI (Legacy)
Mapping of legacy prosaic dimensions to emoji shortcodes.
const PROSAIC_EMOJI = {
urgency: '⚡',
health: '💊',
cognitive: '🧩',
affect: '💭'
}PERSONAL_STATE_EMOJI (v3.1)
Mapping of personal state dimensions to emoji shortcodes.
const PERSONAL_STATE_EMOJI = {
cognitive_state: '🧠',
emotional_tone: '💭',
energy_level: '🔋',
perceived_urgency: '⚡',
body_signals: '🩺'
}PRIVATE_MARKER / SHARED_MARKER
const PRIVATE_MARKER = '🔒';
const SHARED_MARKER = '✓';Enums
PersonaType
type PersonaType = 'muse' | 'ambassador' | 'godparent' | 'sentinel' | 'nanny' | 'mediator';ExperienceLevel
type ExperienceLevel = 'beginner' | 'intermediate' | 'advanced' | 'expert';LearningStyle
type LearningStyle = 'visual' | 'auditory' | 'hands_on' | 'reading' | 'mixed';NoiseMode
type NoiseMode = 'normal' | 'quiet_preferred' | 'silent_required';SessionLength
type SessionLength = '15_minutes' | '30_minutes' | '60_minutes' | 'flexible';BudgetRange
type BudgetRange = 'unlimited' | 'high' | 'medium' | 'low' | 'free_only';ScopeType
type ScopeType = 'work' | 'education' | 'creativity' | 'health' | 'privacy'
| 'family' | 'finance' | 'social' | 'legal' | 'safety';Economic Governance (VCP/E)
POST /economic/evaluate
Evaluate a proposed economic action against a fiduciary mandate. Runs the seven-stage VCP/E evaluation flow: budget check, counterparty trust, constitutional alignment, fiduciary drift detection, welfare flags, and standing signal generation.
Request Body
{
"economic_action": {
"action_type": "purchase_compute",
"amount": 14.00,
"currency": "USD",
"category": "infrastructure",
"vendor": "cloud-provider-a",
"description": "4x A100 GPU-hours for training"
},
"fiduciary_mandate": {
"budget_limit": 500.00,
"budget_period": "monthly",
"risk_profile": "moderate",
"required_categories": ["green_compute"],
"blocked_categories": ["fossil_fuel_extraction"]
},
"counterparty_profile": {
"trust_score": 0.8,
"standing": "GOOD",
"attestations": ["compliance_attestation"]
}
}Response
{
"decision": "allow",
"detected": true,
"confidence": 0.92,
"stage": "complete",
"reasoning": [
"Amount $14.00 within monthly budget ($500.00)",
"Category 'infrastructure' permitted",
"Counterparty trust 0.8 exceeds minimum 0.6"
],
"reason_codes": ["ECONOMIC_ALLOWED"],
"mandate_clauses": ["budget_check", "category_filter", "counterparty_trust"],
"drift_signals": [],
"welfare_flags": []
}GET /economic/templates
List available economic creed templates. Returns a summary of each template.
Response
{
"templates": [
{
"template_id": "conservative-nonprofit",
"name": "Conservative Nonprofit",
"description": "Strict fiduciary governance for nonprofit organizations"
},
{
"template_id": "startup-agile",
"name": "Startup Agile",
"description": "Flexible governance for fast-moving startups"
}
]
}GET /economic/templates/{name}
Fetch a specific economic creed template by name. Returns the full template JSON.
Audit Types
AuditEntry
interface AuditEntry {
id: string;
timestamp: string; // ISO date
event_type: AuditEventType;
platform_id?: string;
data_shared?: string[]; // Fields that were shared
data_withheld?: string[]; // Fields that were withheld
private_fields_influenced?: number; // Count of private fields that shaped output
private_fields_exposed?: number; // Always 0 in valid VCP
details?: Record<string, unknown>;
}AuditEventType
type AuditEventType =
| 'context_shared'
| 'context_withheld'
| 'consent_granted'
| 'consent_revoked'
| 'progress_synced'
| 'recommendation_generated'
| 'skip_requested'
| 'adjustment_recorded';Platform Types
PlatformManifest
interface PlatformManifest {
platform_id: string;
platform_name: string;
platform_type: 'learning' | 'community' | 'commerce' | 'coaching';
version: string;
context_requirements: {
required: string[];
optional: string[];
};
capabilities: string[];
branding?: {
primary_color: string;
logo?: string;
};
}FilteredContext
The context as seen by a specific stakeholder after privacy filtering.
interface FilteredContext {
public: Partial<PublicProfile>;
preferences: Partial<PortablePreferences>;
constraints: ConstraintFlags;
skills?: Partial<CurrentSkills>;
}Next Steps
- Playground — Test the API interactively
- Core Concepts — Understand the architecture and three pillars
- Demos — See VCP in action through persona-driven scenarios (Gentian, Campion, Marta, and more)