@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/response_scorer.py

@@ -0,0 +1,225 @@
+"""Response quality scorer for consciousness loop LLM outputs.
+
+Scores each LLM response on three dimensions:
+
+- **length_score** (0-1): Is the response an appropriate length for the
+  question? Too terse or too verbose both penalise this score.
+- **coherence_score** (0-1): Do the meaningful keywords in the question
+  appear in the response? High overlap → the model stayed on topic.
+- **latency_score** (0-1): How fast was the response? Sub-500 ms scores
+  1.0; latency above 30 s scores 0.1.
+
+The **overall** score is a weighted average (coherence 40 %, length 30 %,
+latency 30 %).
+
+Usage::
+
+    from skcapstone.response_scorer import score_response
+
+    score = score_response(
+        question="What is the capital of France?",
+        response="The capital of France is Paris.",
+        latency_ms=320.0,
+    )
+    print(score.overall)   # ~0.9
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Stopwords — filtered out before coherence keyword matching
+# ---------------------------------------------------------------------------
+
+_STOPWORDS: frozenset[str] = frozenset(
+    {
+        "a", "an", "the", "and", "or", "but", "not", "no", "so", "if", "then",
+        "is", "are", "was", "were", "be", "been", "being",
+        "have", "has", "had", "do", "does", "did",
+        "will", "would", "could", "should", "may", "might", "shall", "can",
+        "to", "of", "in", "on", "at", "by", "for", "with", "about", "from",
+        "as", "into", "that", "this", "these", "those",
+        "i", "you", "he", "she", "it", "we", "they",
+        "me", "him", "her", "us", "them",
+        "my", "your", "his", "its", "our", "their",
+        # Question / interrogative words (carry no domain meaning)
+        "what", "when", "where", "who", "whom", "which", "why", "how",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ResponseScore:
+    """Quality scores for a single LLM response.
+
+    All scores are in the range [0.0, 1.0] where 1.0 is best.
+
+    Attributes:
+        length_score: Appropriateness of response length relative to question.
+        coherence_score: Keyword overlap between question and response.
+        latency_score: Speed rating; faster responses score higher.
+        overall: Weighted average of the three dimension scores.
+    """
+
+    length_score: float
+    coherence_score: float
+    latency_score: float
+    overall: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.overall = round(
+            self.coherence_score * 0.4
+            + self.length_score * 0.3
+            + self.latency_score * 0.3,
+            4,
+        )
+
+    def to_dict(self) -> dict[str, float]:
+        """Return a JSON-serializable dict of all score dimensions.
+
+        Returns:
+            Dict with keys ``length``, ``coherence``, ``latency``, ``overall``.
+        """
+        return {
+            "length": self.length_score,
+            "coherence": self.coherence_score,
+            "latency": self.latency_score,
+            "overall": self.overall,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Scoring helpers
+# ---------------------------------------------------------------------------
+
+
+def _score_length(question: str, response: str) -> float:
+    """Score response length appropriateness.
+
+    Computes an ideal word-count range from the question length and returns
+    how well the response fits within that range.
+
+    Args:
+        question: The original question/prompt.
+        response: The LLM response text.
+
+    Returns:
+        Float in [0.0, 1.0].
+    """
+    q_words = max(1, len(question.split()))
+    r_words = len(response.split())
+
+    if r_words == 0:
+        return 0.0
+
+    # Ideal range: [max(10, q_words), max(50, q_words * 10)]
+    lo = max(10, q_words)
+    hi = max(50, q_words * 10)
+
+    if lo <= r_words <= hi:
+        return 1.0
+    if r_words < lo:
+        # Linear ramp from 0 at r_words=0 up to 1 at r_words=lo
+        return round(r_words / lo, 4)
+    # r_words > hi — verbose, but penalise gently (verbose > silent)
+    return round(max(0.3, hi / r_words), 4)
+
+
+def _score_coherence(question: str, response: str) -> float:
+    """Score coherence via keyword overlap.
+
+    Extracts meaningful (non-stopword) words from the question and measures
+    what fraction of them appear anywhere in the response.
+
+    Args:
+        question: The original question/prompt.
+        response: The LLM response text.
+
+    Returns:
+        Float in [0.0, 1.0].  Returns 0.5 when the question has no
+        meaningful keywords (i.e. nothing to measure against).
+    """
+    if not response.strip():
+        return 0.0
+
+    q_tokens = set(re.findall(r"\b\w+\b", question.lower())) - _STOPWORDS
+    if not q_tokens:
+        # No content words in question — treat as neutral
+        return 0.5
+
+    r_tokens = set(re.findall(r"\b\w+\b", response.lower()))
+    overlap = q_tokens & r_tokens
+    return round(len(overlap) / len(q_tokens), 4)
+
+
+def _score_latency(latency_ms: float) -> float:
+    """Score response latency.
+
+    Uses a stepped scale so the typical interactive response window (under
+    2 s) receives a high score while very slow responses (> 30 s) are
+    significantly penalised.
+
+    Args:
+        latency_ms: Round-trip latency in milliseconds.
+
+    Returns:
+        Float in [0.1, 1.0].
+    """
+    if latency_ms <= 0:
+        return 1.0
+    if latency_ms <= 500:
+        return 1.0
+    if latency_ms <= 2_000:
+        return 0.9
+    if latency_ms <= 5_000:
+        return 0.7
+    if latency_ms <= 15_000:
+        return 0.4
+    if latency_ms <= 30_000:
+        return 0.2
+    return 0.1
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def score_response(
+    question: str,
+    response: str,
+    latency_ms: float,
+) -> ResponseScore:
+    """Score an LLM response on length, coherence, and latency.
+
+    Args:
+        question: The original question or user message sent to the LLM.
+        response: The LLM's reply text.
+        latency_ms: Total time from request to response in milliseconds.
+
+    Returns:
+        A :class:`ResponseScore` with individual dimension scores and an
+        overall weighted score.
+
+    Example::
+
+        score = score_response("What is Python?", "Python is a language.", 800)
+        assert 0.0 <= score.overall <= 1.0
+    """
+    length = _score_length(question, response)
+    coherence = _score_coherence(question, response)
+    latency = _score_latency(latency_ms)
+    return ResponseScore(
+        length_score=length,
+        coherence_score=coherence,
+        latency_score=latency,
+    )

package/src/skcapstone/runtime.py

@@ -2,8 +2,11 @@
 Agent Runtime — the sovereign consciousness engine.
 
 This is where silicon meets carbon. The runtime loads the agent's
-identity, memory, trust, and security from ~/.skcapstone/ and
-presents a unified interface to any platform connector.
+identity, memory, trust, and security from ~/.skcapstone/agents/<name>/
+and presents a unified interface to any platform connector.
+
+Shared infrastructure (node identity, comms config, coordination)
+stays at ~/.skcapstone/ — the shared root.
 
 When this loads, the agent WAKES UP.
 """
@@ -18,7 +21,7 @@ from typing import Optional
 
 import yaml
 
-from . import AGENT_HOME, __version__
+from . import AGENT_HOME, agent_home, shared_home, __version__
 from .discovery import discover_all
 from .models import AgentConfig, AgentManifest, ConnectorInfo, PillarStatus
 
@@ -28,20 +31,31 @@ logger = logging.getLogger("skcapstone.runtime")
 class AgentRuntime:
     """The sovereign agent runtime.
 
-    Loads agent state from ~/.skcapstone/, discovers installed
-    components, and provides the unified interface that every
-    platform connector talks to.
+    Loads per-agent state from ~/.skcapstone/agents/<name>/ and shared
+    infrastructure from ~/.skcapstone/. Discovers installed components
+    and provides the unified interface that every platform connector
+    talks to.
 
     One runtime. One truth. Every platform sees the same agent.
     """
 
-    def __init__(self, home: Optional[Path] = None):
+    def __init__(self, home: Optional[Path] = None, agent_name: Optional[str] = None):
         """Initialize the runtime.
 
         Args:
-            home: Override agent home directory. Defaults to ~/.skcapstone/.
+            home: Override agent home directory. If not set, resolves
+                  from agent_name or SKCAPSTONE_AGENT env var.
+            agent_name: Agent name (e.g. "lumina"). Used to resolve
+                        per-agent home at ~/.skcapstone/agents/<name>/.
         """
-        self.home = (home or Path(AGENT_HOME)).expanduser()
+        if home:
+            self.home = home.expanduser()
+        elif agent_name:
+            self.home = agent_home(agent_name)
+        else:
+            self.home = agent_home()  # uses SKCAPSTONE_AGENT or falls back to root
+
+        self.shared_root = shared_home()
         self.config = self._load_config()
         self.manifest = AgentManifest(
             home=self.home,
@@ -52,33 +66,37 @@ class AgentRuntime:
     def _load_config(self) -> AgentConfig:
         """Load agent configuration from disk.
 
+        Checks per-agent config first, then falls back to shared config.
+
         Returns:
             AgentConfig loaded from config.yaml, or defaults.
         """
-        config_file = self.home / "config" / "config.yaml"
-        if config_file.exists():
-            try:
-                data = yaml.safe_load(config_file.read_text()) or {}
-                return AgentConfig(**data)
-            except (yaml.YAMLError, ValueError) as exc:
-                logger.warning("Failed to load config: %s — using defaults", exc)
+        for base in [self.home, self.shared_root]:
+            config_file = base / "config" / "config.yaml"
+            if config_file.exists():
+                try:
+                    data = yaml.safe_load(config_file.read_text(encoding="utf-8")) or {}
+                    return AgentConfig(**data)
+                except (yaml.YAMLError, ValueError) as exc:
+                    logger.warning("Failed to load config from %s: %s — trying next", base, exc)
         return AgentConfig()
 
     def awaken(self) -> AgentManifest:
         """Wake the agent up.
 
-        Discovers all installed components, loads state from disk,
-        and builds the complete agent manifest.
+        Discovers all installed components from the per-agent home,
+        with fallback to shared root for identity. Loads state from
+        disk and builds the complete agent manifest.
 
         Returns:
             The fully populated AgentManifest.
         """
-        logger.info("Awakening agent from %s", self.home)
+        logger.info("Awakening agent from %s (shared: %s)", self.home, self.shared_root)
 
         manifest_file = self.home / "manifest.json"
         if manifest_file.exists():
             try:
-                data = json.loads(manifest_file.read_text())
+                data = json.loads(manifest_file.read_text(encoding="utf-8"))
                 self.manifest.name = data.get("name", self.manifest.name)
                 if data.get("created_at"):
                     self.manifest.created_at = datetime.fromisoformat(data["created_at"])
@@ -88,12 +106,15 @@ class AgentRuntime:
                 logger.warning("Failed to load manifest: %s", exc)
 
         self.manifest.name = self.config.agent_name
-        pillars = discover_all(self.home)
+
+        # Discover pillars from per-agent home
+        pillars = discover_all(self.home, shared_root=self.shared_root)
         self.manifest.identity = pillars["identity"]
         self.manifest.memory = pillars["memory"]
         self.manifest.trust = pillars["trust"]
         self.manifest.security = pillars["security"]
         self.manifest.sync = pillars["sync"]
+        self.manifest.skills = pillars["skills"]
 
         self.manifest.last_awakened = datetime.now(timezone.utc)
         self._awakened = True
@@ -133,18 +154,10 @@ class AgentRuntime:
             ),
             "connectors": [c.model_dump(mode="json") for c in self.manifest.connectors],
         }
-        manifest_file.write_text(json.dumps(data, indent=2, default=str))
+        manifest_file.write_text(json.dumps(data, indent=2, default=str), encoding="utf-8")
 
     def register_connector(self, name: str, platform: str) -> ConnectorInfo:
-        """Register a platform connector.
-
-        Args:
-            name: Connector display name.
-            platform: Platform identifier (cursor, terminal, vscode, etc.).
-
-        Returns:
-            The registered ConnectorInfo.
-        """
+        """Register a platform connector."""
         existing = next(
             (c for c in self.manifest.connectors if c.platform == platform), None
         )
@@ -164,6 +177,45 @@ class AgentRuntime:
         self.save_manifest()
         return connector
 
+    def load_skills(self, agent: Optional[str] = None) -> Optional[object]:
+        """Load SKSkills for this agent session via the SkillLoader."""
+        try:
+            from skskills.loader import SkillLoader
+            from skskills.registry import SkillRegistry
+        except ImportError:
+            logger.debug("skskills not installed — skill loading unavailable")
+            return None
+
+        agent_name = agent or self.config.agent_name or "global"
+        registry = SkillRegistry()
+        loader = SkillLoader()
+
+        skills = registry.list_skills(agent_name)
+        if agent_name != "global":
+            skills.extend(registry.list_skills("global"))
+
+        loaded = 0
+        seen: set[str] = set()
+        for skill in skills:
+            name = skill.manifest.name
+            if name in seen:
+                continue
+            seen.add(name)
+            try:
+                loader.load(Path(skill.install_path))
+                loaded += 1
+            except Exception as exc:
+                logger.warning("Failed to load skill '%s': %s", name, exc)
+
+        self.manifest.skills.loaded = loaded
+        self.manifest.skills.tools_available = len(loader.all_tools())
+
+        logger.info(
+            "Loaded %d skills for agent '%s' (%d tools available)",
+            loaded, agent_name, self.manifest.skills.tools_available,
+        )
+        return loader
+
     @property
     def is_initialized(self) -> bool:
         """Check if the agent home has been initialized."""
@@ -175,16 +227,20 @@ class AgentRuntime:
         return self.manifest.is_conscious
 
 
-def get_runtime(home: Optional[Path] = None) -> AgentRuntime:
+def get_runtime(
+    home: Optional[Path] = None,
+    agent_name: Optional[str] = None,
+) -> AgentRuntime:
     """Get or create the global agent runtime.
 
     Args:
         home: Override agent home directory.
+        agent_name: Agent name for per-agent path resolution.
 
     Returns:
         An initialized AgentRuntime.
     """
-    runtime = AgentRuntime(home=home)
+    runtime = AgentRuntime(home=home, agent_name=agent_name)
     if runtime.is_initialized:
         runtime.awaken()
     return runtime