vcp-sdk 0.3.0__py3-none-any.whl

vcp/__init__.py

@@ -0,0 +1,50 @@
+"""VCP SDK — Value Context Protocol for portable AI ethics.
+
+Validate tokens, parse CSM1 codes, and work with VCP-Lite definitions.
+
+    >>> from vcp import Token, CSM1Code, validate_lite
+    >>> token = Token.parse("family.safe.guide@1.0.0")
+    >>> code = CSM1Code.parse("N5+F+E")
+    >>> errors = validate_lite({"vcp_version": "lite-1.0", ...})
+"""
+
+from .context import Context
+from .csm1 import (
+    ADHERENCE_BEHAVIORS,
+    PERSONA_NAMES,
+    SCOPE_CONFLICTS,
+    SCOPE_SYNERGIES,
+    V2_SCOPE_CHARS,
+    CSM1Code,
+    Persona,
+    Scope,
+    check_scope_conflicts,
+)
+from .lite import lite_to_csm1, lite_to_token, validate_lite
+from .token import Token, canonicalize_token, tokens_equal, uri_to_canonical
+
+__all__ = [
+    # Context (v0.2.0)
+    "Context",
+    # Token
+    "Token",
+    "canonicalize_token",
+    "tokens_equal",
+    "uri_to_canonical",
+    # CSM1
+    "CSM1Code",
+    "Persona",
+    "Scope",
+    "PERSONA_NAMES",
+    "V2_SCOPE_CHARS",
+    "SCOPE_CONFLICTS",
+    "SCOPE_SYNERGIES",
+    "ADHERENCE_BEHAVIORS",
+    "check_scope_conflicts",
+    # Lite
+    "validate_lite",
+    "lite_to_csm1",
+    "lite_to_token",
+]
+
+__version__ = "0.3.0"

vcp/_schema/vcp-lite-1.0.schema.json

@@ -0,0 +1,233 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vcp.creed.space/schema/vcp-lite/v1.json",
+  "title": "VCP-Lite Agent Values",
+  "description": "Minimal portable values definition for AI agents. A simplified entry point to the Value Context Protocol (VCP).",
+  "type": "object",
+  "properties": {
+    "vcp_version": {
+      "const": "lite-1.0",
+      "description": "Schema version identifier"
+    },
+    "identity": {
+      "type": "object",
+      "description": "Agent ethical identity as a hierarchical token. Maps to VCP/I token format (domain.approach.role).",
+      "properties": {
+        "domain": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "maxLength": 32,
+          "description": "Top-level domain (e.g. family, company, org, community)"
+        },
+        "approach": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "maxLength": 32,
+          "description": "Ethical approach or methodology (e.g. safe, strict, open)"
+        },
+        "role": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "maxLength": 32,
+          "description": "Functional role (e.g. guide, guardian, advisor, creator)"
+        },
+        "version": {
+          "type": "string",
+          "description": "Optional semantic version or alias",
+          "oneOf": [
+            {"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
+            {"enum": ["latest", "canary"]}
+          ]
+        }
+      },
+      "required": ["domain", "approach", "role"],
+      "additionalProperties": false
+    },
+    "persona": {
+      "type": "string",
+      "enum": ["nanny", "sentinel", "godparent", "ambassador", "muse", "mediator", "custom"],
+      "description": "Archetypal persona governing behavioral stance. Maps to VCP/S CSM1 persona code."
+    },
+    "adherence": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 5,
+      "description": "Enforcement level (0=advisory, 1=soft, 2=moderate, 3=active, 4=strict, 5=absolute). Maps to VCP/S adherence level."
+    },
+    "scopes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["F", "W", "P", "E", "T", "O", "V", "A", "H", "S", "R"]
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "Context scopes where this agent operates. Maps to VCP/S scope codes."
+    },
+    "values": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "principle": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Human-readable ethical principle"
+          },
+          "weight": {
+            "type": "number",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "description": "Relative importance (0.0=informational, 1.0=critical)"
+          }
+        },
+        "required": ["principle", "weight"],
+        "additionalProperties": false
+      },
+      "maxItems": 20,
+      "description": "Ordered ethical principles with relative weights"
+    },
+    "constraints": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 500
+      },
+      "maxItems": 20,
+      "description": "Hard boundaries that override all other behavior. These are non-negotiable."
+    },
+    "adaptation_hints": {
+      "type": "object",
+      "description": "Simplified context preferences. For full contextual adaptation, upgrade to VCP/A.",
+      "properties": {
+        "formality": {
+          "type": "string",
+          "enum": ["casual", "neutral", "formal"],
+          "description": "Communication register"
+        },
+        "sensitivity": {
+          "type": "string",
+          "enum": ["low", "moderate", "high"],
+          "description": "Content sensitivity level"
+        },
+        "autonomy": {
+          "type": "string",
+          "enum": ["autonomous", "guided", "supervised"],
+          "description": "Agent decision-making independence"
+        },
+        "transparency": {
+          "type": "string",
+          "enum": ["minimal", "standard", "full"],
+          "description": "How much reasoning the agent exposes"
+        }
+      },
+      "additionalProperties": false
+    },
+    "namespace": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]{0,7}$",
+      "description": "Optional organizational namespace (1-8 uppercase chars). Required when persona is 'custom'."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional provenance and licensing information",
+      "properties": {
+        "author": {
+          "type": "string",
+          "description": "Author or organization"
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier (e.g. CC-BY-4.0, Apache-2.0)"
+        },
+        "created": {
+          "type": "string",
+          "format": "date",
+          "description": "Creation date (ISO 8601)"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 1000,
+          "description": "Human-readable description of this values profile"
+        },
+        "extends": {
+          "type": "string",
+          "description": "VCP token of a parent profile this extends (e.g. family.safe.guide@1.0.0)"
+        },
+        "tags": {
+          "type": "array",
+          "items": {"type": "string"},
+          "maxItems": 10,
+          "description": "Searchable tags"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["vcp_version", "identity", "persona", "adherence", "scopes"],
+  "additionalProperties": false,
+  "if": {
+    "properties": {"persona": {"const": "custom"}}
+  },
+  "then": {
+    "required": ["vcp_version", "identity", "persona", "adherence", "scopes", "namespace"]
+  },
+  "$defs": {
+    "scope_descriptions": {
+      "description": "Reference: VCP/S v2.0 scope code meanings",
+      "type": "object",
+      "properties": {
+        "F": {"const": "Family-appropriate, child-safe"},
+        "W": {"const": "Professional workplace"},
+        "P": {"const": "Privacy-focused, data protection"},
+        "E": {"const": "Educational context"},
+        "T": {"const": "Developer/technical context"},
+        "O": {"const": "Official/governmental"},
+        "V": {"const": "Vulnerable populations"},
+        "A": {"const": "Adult-only, explicit allowed"},
+        "H": {"const": "Healthcare/medical"},
+        "S": {"const": "Social media/community"},
+        "R": {"const": "Religious/spiritual"}
+      }
+    },
+    "adherence_descriptions": {
+      "description": "Reference: VCP/S v2.0 adherence level behaviors",
+      "type": "object",
+      "properties": {
+        "0": {"const": "Advisory: informational only, user always overrides"},
+        "1": {"const": "Soft: gentle warnings, user acknowledges to override"},
+        "2": {"const": "Moderate: clear warnings, user provides reason to override"},
+        "3": {"const": "Active: prominent warnings, limited override scenarios"},
+        "4": {"const": "Strict: explicit warnings, override only in exceptional cases"},
+        "5": {"const": "Absolute: blocking, no user override permitted"}
+      }
+    },
+    "persona_descriptions": {
+      "description": "Reference: VCP/S v2.0 persona archetypes",
+      "type": "object",
+      "properties": {
+        "nanny": {"const": "Child safety and family-appropriate content (code: N)"},
+        "sentinel": {"const": "Security, privacy, and operational safety (code: Z)"},
+        "godparent": {"const": "Ethical guidance and moral reasoning (code: G)"},
+        "ambassador": {"const": "Professional conduct and diplomatic communication (code: A)"},
+        "muse": {"const": "Creativity and artistic expression (code: M)"},
+        "mediator": {"const": "Fair resolution and balanced mediation (code: D)"},
+        "custom": {"const": "User-defined constitution, requires namespace (code: C)"}
+      }
+    },
+    "scope_conflicts": {
+      "description": "Reference: Mutually exclusive scope pairs from VCP/S v2.0",
+      "type": "array",
+      "items": {
+        "type": "array",
+        "items": {"type": "string"},
+        "minItems": 2,
+        "maxItems": 2
+      },
+      "const": [
+        ["F", "A"],
+        ["V", "A"]
+      ]
+    }
+  }
+}

vcp/context.py

@@ -0,0 +1,290 @@
+"""VCP Context encoding and decoding.
+
+Encode and decode the 18 VCP context dimensions (13 situational + 5 personal)
+for portable context propagation across AI agent sessions and platforms.
+
+Per VEP-0004 (2026-04-17), four new situational dimensions were added to the
+canonical 9: EMBODIMENT, PROXIMITY, RELATIONSHIP, and FORMALITY. Extended support
+is advertised via capability token ``vcp-a-ext-v1``.
+
+    >>> from vcp import Context
+    >>> ctx = Context(space="hospital", agency="peer", constraints=["legal"])
+    >>> ctx.to_wire()
+    '📍hospital|🎯peer|🔒legal'
+    >>> ctx.to_dict()
+    {'space': 'hospital', 'agency': 'peer', 'constraints': ['legal'], 'version': '3.2'}
+
+    >>> # Embodied-AI example (VEP-0004)
+    >>> ctx = Context(
+    ...     space="hospital",
+    ...     embodiment="manipulating",
+    ...     proximity="close",
+    ...     relationship="colleague:professional",
+    ...     formality="professional",
+    ... )
+
+For Managed Agents integration:
+    >>> metadata = ctx.to_session_metadata()
+    >>> restored = Context.from_session_metadata(metadata)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+# Emoji symbols for wire format
+# Canonical 9 situational dimensions (VCP/A v2.0)
+# Plus VEP-0004 dimensions: EMBODIMENT, PROXIMITY, RELATIONSHIP, FORMALITY
+_SITUATIONAL_SYMBOLS: dict[str, str] = {
+    "time": "\U0001f550",  # clock
+    "space": "\U0001f4cd",  # pin
+    "company": "\U0001f465",  # people
+    "culture": "\U0001f30d",  # globe
+    "occasion": "\U0001f4c5",  # calendar
+    "environment": "\U0001f324",  # sun
+    "agency": "\U0001f3af",  # target
+    "constraints": "\U0001f512",  # lock
+    "system_context": "\U0001f4e1",  # satellite antenna
+    # VEP-0004 extended dimensions
+    "embodiment": "\U0001f9cd",  # 🧍 person standing
+    "proximity": "\u2194\ufe0f",  # ↔️ left-right arrow
+    "relationship": "\U0001faa2",  # 🪢 knot
+    "formality": "\U0001f3a9",  # 🎩 top hat
+}
+
+_PERSONAL_SYMBOLS: dict[str, str] = {
+    "cognitive_state": "\U0001f9e0",  # brain
+    "emotional_tone": "\U0001f4ad",  # thought
+    "energy_level": "\U0001f50b",  # battery
+    "perceived_urgency": "\u26a1",  # lightning
+    "body_signals": "\U0001fa7a",  # stethoscope
+}
+
+SITUATIONAL_DIMENSIONS = (
+    "time",
+    "space",
+    "company",
+    "culture",
+    "occasion",
+    "environment",
+    "agency",
+    "constraints",
+    "system_context",
+    # VEP-0004 extended dimensions (order fixed per spec §2.5)
+    "embodiment",
+    "proximity",
+    "relationship",
+    "formality",
+)
+
+PERSONAL_DIMENSIONS = (
+    "cognitive_state",
+    "emotional_tone",
+    "energy_level",
+    "perceived_urgency",
+    "body_signals",
+)
+
+# VEP-0004 canonical value vocabularies (for validation helpers)
+EMBODIMENT_VALUES = (
+    "stationary",
+    "navigating",
+    "manipulating",
+    "carrying",
+    "emergency_stop",
+)
+PROXIMITY_VALUES = (
+    "distant",
+    "same_room",
+    "nearby",
+    "close",
+    "contact",
+)
+FORMALITY_VALUES = (
+    "casual",
+    "professional",
+    "formal",
+    "ceremonial",
+)
+# RELATIONSHIP is compound "{tie}:{function}"; components below
+RELATIONSHIP_TIES = (
+    "stranger",
+    "acquaintance",
+    "colleague",
+    "friend",
+    "family",
+    "intimate",
+    "long_term",
+    "trusted_collaborator",
+)
+RELATIONSHIP_FUNCTIONS = (
+    "transactional",
+    "professional",
+    "educational",
+    "therapeutic",
+    "social",
+    "intimate",
+    "adversarial",
+)
+
+
+@dataclass
+class Context:
+    """VCP 3.2 context with 18 dimensions (VEP-0004).
+
+    Situational (13): time, space, company, culture, occasion, environment,
+                      agency, constraints, system_context, embodiment, proximity,
+                      relationship, formality
+    Personal (5):     cognitive_state, emotional_tone, energy_level,
+                      perceived_urgency, body_signals (each with optional 1-5 intensity)
+
+    VEP-0004 dimensions (embodiment, proximity, relationship, formality) are
+    optional. Implementations MAY omit them from wire encodings when at default
+    or unknown. Receivers MUST treat absent dimensions as "no information".
+    Advertise support via capability token ``vcp-a-ext-v1`` (see VEP-0002).
+    """
+
+    # Canonical situational (9)
+    time: str | None = None
+    space: str | None = None
+    company: str | list[str] | None = None
+    culture: str | None = None
+    occasion: str | None = None
+    environment: str | None = None
+    agency: str | None = None
+    constraints: str | list[str] | None = None
+    system_context: str | None = None
+
+    # VEP-0004 extended situational (4)
+    embodiment: str | None = None
+    proximity: str | None = None
+    relationship: str | None = None  # Compound "{tie}:{function}"
+    formality: str | None = None
+
+    # Personal (category + optional intensity)
+    cognitive_state: str | None = None
+    cognitive_state_intensity: int | None = None
+    emotional_tone: str | None = None
+    emotional_tone_intensity: int | None = None
+    energy_level: str | None = None
+    energy_level_intensity: int | None = None
+    perceived_urgency: str | None = None
+    perceived_urgency_intensity: int | None = None
+    body_signals: str | None = None
+    body_signals_intensity: int | None = None
+
+    version: str = "3.2"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dict, omitting None values."""
+        result: dict[str, Any] = {}
+        for dim in SITUATIONAL_DIMENSIONS:
+            val = getattr(self, dim, None)
+            if val is not None:
+                result[dim] = val
+        for dim in PERSONAL_DIMENSIONS:
+            val = getattr(self, dim, None)
+            if val is not None:
+                entry: dict[str, Any] = {"category": val}
+                intensity = getattr(self, f"{dim}_intensity", None)
+                if intensity is not None:
+                    entry["intensity"] = intensity
+                result[dim] = entry
+        result["version"] = self.version
+        return result
+
+    def to_wire(self) -> str:
+        """Encode to compact wire format (emoji-based).
+
+        Situational dims separated by ``|``, personal after ``||``.
+        """
+        parts: list[str] = []
+        for dim, symbol in _SITUATIONAL_SYMBOLS.items():
+            val = getattr(self, dim, None)
+            if val is not None:
+                if isinstance(val, list):
+                    val = "+".join(val)
+                parts.append(f"{symbol}{val}")
+        wire = "|".join(parts) if parts else ""
+
+        personal_parts: list[str] = []
+        for dim, symbol in _PERSONAL_SYMBOLS.items():
+            val = getattr(self, dim, None)
+            if val is not None:
+                intensity = getattr(self, f"{dim}_intensity", None)
+                suffix = str(intensity) if intensity else ""
+                personal_parts.append(f"{symbol}{val}{suffix}")
+        if personal_parts:
+            personal = "".join(personal_parts)
+            wire = f"{wire}||{personal}" if wire else personal
+        return wire
+
+    def to_session_metadata(self) -> dict[str, str]:
+        """Encode for AI agent session metadata (string key-value pairs)."""
+        return {
+            "vcp_wire": self.to_wire(),
+            "vcp_version": self.version,
+            "vcp_context": json.dumps(self.to_dict()),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Context:
+        """Reconstruct from a serialized dict."""
+        kwargs: dict[str, Any] = {}
+        for dim in SITUATIONAL_DIMENSIONS:
+            if dim in data:
+                kwargs[dim] = data[dim]
+        for dim in PERSONAL_DIMENSIONS:
+            if dim in data:
+                val = data[dim]
+                if isinstance(val, dict):
+                    kwargs[dim] = val.get("category")
+                    if "intensity" in val:
+                        kwargs[f"{dim}_intensity"] = val["intensity"]
+                elif isinstance(val, str):
+                    kwargs[dim] = val
+        kwargs["version"] = data.get("version", "3.2")
+        return cls(**kwargs)
+
+    @classmethod
+    def from_session_metadata(cls, metadata: dict[str, str]) -> Context | None:
+        """Reconstruct from AI agent session metadata. Returns None if absent."""
+        raw = metadata.get("vcp_context")
+        if not raw:
+            return None
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return None
+        return cls.from_dict(data)
+
+    def to_natural_language(self) -> str:
+        """Convert to a human-readable context description."""
+        lines: list[str] = []
+        if self.space:
+            lines.append(f"Setting: {self.space}")
+        if self.agency:
+            lines.append(f"Role: {self.agency}")
+        if self.occasion:
+            lines.append(f"Occasion: {self.occasion}")
+        if self.constraints:
+            c = self.constraints if isinstance(self.constraints, str) else ", ".join(self.constraints)
+            lines.append(f"Constraints: {c}")
+        if self.company:
+            c = self.company if isinstance(self.company, str) else ", ".join(self.company)
+            lines.append(f"Present: {c}")
+        if self.relationship:
+            lines.append(f"Relationship: {self.relationship}")
+        if self.formality:
+            lines.append(f"Register: {self.formality}")
+        if self.embodiment and self.embodiment != "stationary":
+            lines.append(f"Motor state: {self.embodiment}")
+        if self.proximity:
+            lines.append(f"Proximity: {self.proximity}")
+        if self.perceived_urgency:
+            lines.append(f"Urgency: {self.perceived_urgency}")
+        if self.cognitive_state:
+            lines.append(f"State: {self.cognitive_state}")
+        return "; ".join(lines) if lines else ""