skillware 0.3.6__tar.gz → 0.3.8__tar.gz

{skillware-0.3.6 → skillware-0.3.8}/MANIFEST.in

@@ -1,3 +1,4 @@
 graft skills
+include examples/README.md
 global-exclude __pycache__
 global-exclude *.py[cod]

{skillware-0.3.6/skillware.egg-info → skillware-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.6
+Version: 0.3.8
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -79,7 +79,7 @@ Dynamic: license-file
 
 <div align="center">
   <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
-  <img src="https://img.shields.io/badge/Python-3.11+-bae6fd?style=flat-square" alt="Python Version">
+  <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
   <a href="https://pypi.org/project/skillware/"><img src="https://img.shields.io/pypi/v/skillware?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
 </div>
 
@@ -150,6 +150,8 @@ Skillware/
 
 ## Quick Start
 
+Requires **Python 3.10 or newer** (see `requires-python` in `pyproject.toml`).
+
 ### 1. Installation
 
 You can install Skillware directly from PyPI:
@@ -163,9 +165,11 @@ Or for development, clone the repository and install in editable mode:
 ```bash
 git clone https://github.com/arpahls/skillware.git
 cd skillware
-pip install -e .
+pip install -e ".[dev,all]"
 ```
 
+For documentation-only work, `pip install -e ".[dev]"` is enough. Skill and framework contributors should use `[dev,all]` to match CI (see [TESTING.md](docs/TESTING.md)).
+
 > **Note**: Individual skills may have their own dependencies. The `SkillLoader` validates `manifest.yaml` and warns of missing packages (e.g., `requests`, `pandas`) upon loading a skill.
 
 ### 2. Verify your installation
@@ -184,12 +188,22 @@ your PATH — use `python -m skillware list` as a fallback. See
 
 ### 3. Configuration
 
-Create a `.env` file with your API keys (e.g., Google Gemini API Key):
+Copy the environment template and add your keys.
+
+**Unix / macOS:**
+
+```bash
+cp .env.example .env
+```
 
-```ini
-GOOGLE_API_KEY="your_key"
+**Windows (PowerShell):**
+
+```powershell
+Copy-Item .env.example .env
 ```
 
+Edit `.env` with agent keys (for example Gemini) and any keys your skills need. Agent keys power your LLM client; skill keys are declared per skill in the [Skill library](docs/skills/README.md). See [API keys for skills](docs/usage/api_keys.md) for setup, security, and framework variables.
+
 ### 4. Usage Example (Gemini)
 
 This example requires the Google SDK optional extra: `pip install "skillware[gemini]"` (local dev: `pip install -e ".[gemini]"`). See the [Gemini usage guide](docs/usage/gemini.md) for setup details.

{skillware-0.3.6 → skillware-0.3.8}/README.md

@@ -8,7 +8,7 @@
 
 <div align="center">
   <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
-  <img src="https://img.shields.io/badge/Python-3.11+-bae6fd?style=flat-square" alt="Python Version">
+  <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
   <a href="https://pypi.org/project/skillware/"><img src="https://img.shields.io/pypi/v/skillware?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
 </div>
 
@@ -79,6 +79,8 @@ Skillware/
 
 ## Quick Start
 
+Requires **Python 3.10 or newer** (see `requires-python` in `pyproject.toml`).
+
 ### 1. Installation
 
 You can install Skillware directly from PyPI:
@@ -92,9 +94,11 @@ Or for development, clone the repository and install in editable mode:
 ```bash
 git clone https://github.com/arpahls/skillware.git
 cd skillware
-pip install -e .
+pip install -e ".[dev,all]"
 ```
 
+For documentation-only work, `pip install -e ".[dev]"` is enough. Skill and framework contributors should use `[dev,all]` to match CI (see [TESTING.md](docs/TESTING.md)).
+
 > **Note**: Individual skills may have their own dependencies. The `SkillLoader` validates `manifest.yaml` and warns of missing packages (e.g., `requests`, `pandas`) upon loading a skill.
 
 ### 2. Verify your installation
@@ -113,12 +117,22 @@ your PATH — use `python -m skillware list` as a fallback. See
 
 ### 3. Configuration
 
-Create a `.env` file with your API keys (e.g., Google Gemini API Key):
+Copy the environment template and add your keys.
+
+**Unix / macOS:**
+
+```bash
+cp .env.example .env
+```
 
-```ini
-GOOGLE_API_KEY="your_key"
+**Windows (PowerShell):**
+
+```powershell
+Copy-Item .env.example .env
 ```
 
+Edit `.env` with agent keys (for example Gemini) and any keys your skills need. Agent keys power your LLM client; skill keys are declared per skill in the [Skill library](docs/skills/README.md). See [API keys for skills](docs/usage/api_keys.md) for setup, security, and framework variables.
+
 ### 4. Usage Example (Gemini)
 
 This example requires the Google SDK optional extra: `pip install "skillware[gemini]"` (local dev: `pip install -e ".[gemini]"`). See the [Gemini usage guide](docs/usage/gemini.md) for setup details.

skillware-0.3.8/examples/README.md

@@ -0,0 +1,61 @@
+# Skillware Examples Index
+
+> **These are usage examples, not tests.** Runnable provider demos live here; automated tests live in `skills/**/test_skill.py` (bundle) and `tests/` (framework and optional maintainer depth). See [TESTING.md](../docs/TESTING.md).
+
+Runnable examples in this directory show how to load Skillware skills, adapt
+them for a provider, execute local skill logic, and return tool results to an
+agent loop. From the repository root, run `skillware examples` or
+`skillware list --examples` to browse the index in the terminal (see
+[CLI reference](../docs/usage/cli.md)). Provider setup details live in the usage guides:
+
+- [API keys for skills](../docs/usage/api_keys.md)
+- [Gemini](../docs/usage/gemini.md)
+- [Claude](../docs/usage/claude.md)
+- [OpenAI](../docs/usage/openai.md)
+- [DeepSeek](../docs/usage/deepseek.md)
+- [Ollama](../docs/usage/ollama.md)
+- [Agent loops](../docs/usage/agent_loops.md)
+
+Use the package extra shown below when installing from PyPI:
+`pip install "skillware[gemini]"`. For local development, use the same extra
+with editable install: `pip install -e ".[gemini]"`.
+
+## Runnable Scripts
+
+| Script | Skill ID | Provider | Required extra | Required env vars | Description |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `mental_coach_demo.py` | `wellness/mental_coach` | Local execute | base install only | None | Demonstrates coaching, crisis escalation, and blocked clinical paths locally. |
+| `build_dataset_demo.py` | `data_engineering/synthetic_generator` | Local execute (Gemini backend) | `[gemini]` | `GOOGLE_API_KEY` | Generates a JSONL synthetic dataset with the synthetic generator skill. |
+| `claude_pdf_form_filler.py` | `office/pdf_form_filler` | Claude | `[claude]`, `[office]` | `ANTHROPIC_API_KEY` | Uses Claude with the PDF form filler skill to map instructions to fields. |
+| `claude_tos_evaluator.py` | `compliance/tos_evaluator` | Claude | `[claude]` | `ANTHROPIC_API_KEY` | Runs a Claude tool loop for website automation policy review. |
+| `claude_issue_resolver.py` | `dev_tools/issue_resolver` | Claude | `[claude]` | `ANTHROPIC_API_KEY`; optional `GITHUB_TOKEN` | Claude loop for GitHub issue analysis; fetches issue data after `prepare` (sample: issue #123). |
+| `claude_wallet_check.py` | `finance/wallet_screening` | Claude | `[claude]` | `ANTHROPIC_API_KEY`, `ETHERSCAN_API_KEY` | Screens an Ethereum wallet and returns the result through a Claude tool loop. |
+| `deepseek_tos_evaluator.py` | `compliance/tos_evaluator` | DeepSeek | `[openai]` | `DEEPSEEK_API_KEY` | Uses the OpenAI-compatible DeepSeek API for terms-of-service evaluation. |
+| `gemini_pdf_form_filler.py` | `office/pdf_form_filler` | Gemini | `[gemini]`, `[office]` | `GOOGLE_API_KEY`, `ANTHROPIC_API_KEY` | Uses Gemini as the agent while the PDF skill calls Anthropic for form filling. |
+| `gemini_tos_evaluator.py` | `compliance/tos_evaluator` | Gemini | `[gemini]` | `GOOGLE_API_KEY` | Runs the terms-of-service evaluator with a Gemini function-calling loop. |
+| `gemini_wallet_check.py` | `finance/wallet_screening` | Gemini | `[gemini]` | `GOOGLE_API_KEY`, `ETHERSCAN_API_KEY` | Screens an Ethereum wallet with Gemini orchestration and Etherscan data. |
+| `gemini_evm_tx_handler.py` | `defi/evm_tx_handler` | Gemini | `[gemini]` | `GOOGLE_API_KEY`; for live swaps also `AGENT_WALLET_PRIVATE_KEY`, `BASE_RPC_URL` or `ETHEREUM_RPC_URL`. Set `EVM_TX_HANDLER_EXAMPLE_DEMO=1` for mocked flow without keys. | Resolve → quote → preview → execute buy flow via Gemini tool loop (or demo mode). |
+| `claude_evm_tx_handler.py` | `defi/evm_tx_handler` | Claude | `[claude]` | `ANTHROPIC_API_KEY`; for live swaps also `AGENT_WALLET_PRIVATE_KEY`, RPC URLs. Demo: `EVM_TX_HANDLER_EXAMPLE_DEMO=1`. | Claude tool loop for structured DeFi intent and optional execute after confirmation. |
+| `mica_claude_flow.py` | `compliance/mica_module` | Claude | `[claude]` | `ANTHROPIC_API_KEY` | Runs a MiCA compliance agent loop through Claude. |
+| `mica_ollama_flow.py` | `compliance/mica_module` | Ollama | No Skillware extra; install `ollama` separately | None | Runs a local Ollama MiCA flow with prompt-mode tool calling. |
+| `mica_rag_flow.py` | `compliance/mica_module` | Gemini | `[gemini]` | `GOOGLE_API_KEY` | Runs the MiCA RAG flow with Gemini. |
+| `ollama_skills_test.py` | `finance/wallet_screening`, `office/pdf_form_filler`, `optimization/prompt_rewriter` | Ollama | `[office]`; install `ollama` separately | `ETHERSCAN_API_KEY`, `ANTHROPIC_API_KEY` | Loads multiple skills and tests prompt-mode tool calling with Ollama. |
+| `ollama_tos_evaluator.py` | `compliance/tos_evaluator` | Ollama | No Skillware extra; install `ollama` separately | None | Runs the terms-of-service evaluator with local Ollama prompt-mode calls. |
+| `openai_tos_evaluator.py` | `compliance/tos_evaluator` | OpenAI | `[openai]` | `OPENAI_API_KEY` | Runs the terms-of-service evaluator with OpenAI function calling. |
+| `pii_guardrail_flow.py` | `compliance/pii_masker` | Local execute | base install only | None | Demonstrates local PII masking before passing text to an external agent. |
+| `prompt_compression_demo.py` | `optimization/prompt_rewriter` | Local execute | base install only | None | Demonstrates prompt compression without a provider loop. |
+| `novelty_extractor_demo.py` | `data_engineering/novelty_extractor` | Local execute | `pip install fastembed numpy` | None | Demonstrates multi-turn corpus distillation using local embeddings with no API key. |
+| `gemini_novelty_extractor.py` | `data_engineering/novelty_extractor` | Gemini | `[gemini]`, `pip install fastembed numpy` | `GOOGLE_API_KEY` | Runs the novelty extractor with a Gemini function-calling loop. |
+| `ollama_novelty_extractor.py` | `data_engineering/novelty_extractor` | Ollama | `pip install fastembed numpy`; install `ollama` separately | None | Runs the novelty extractor with local Ollama prompt-mode calls. |
+| `gemini_issue_resolver.py` | `dev_tools/issue_resolver` | Gemini | `[gemini]` | `GOOGLE_API_KEY`; optional `GITHUB_TOKEN` | Gemini loop for GitHub issue analysis; fetches issue data after `prepare` (sample: issue #123). |
+| `ollama_issue_resolver.py` | `dev_tools/issue_resolver` | Ollama | No Skillware extra; install `ollama` separately | optional `GITHUB_TOKEN`; `OLLAMA_MODEL` (default `gemma4:e2b`) | Ollama prompt-mode loop for GitHub issue analysis (sample: issue #123). |
+
+## Notes
+
+- Agent-side model keys such as `GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`,
+  `OPENAI_API_KEY`, and `DEEPSEEK_API_KEY` are documented in the provider
+  guides.
+- Skill runtime keys such as `ETHERSCAN_API_KEY` are documented in each skill
+  manifest and on the skill catalog pages.
+- Ollama examples require the Python `ollama` package, a local Ollama server,
+  and the model named in the script, but no cloud API key.

{skillware-0.3.6 → skillware-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.3.6"
+version = "0.3.8"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [

{skillware-0.3.6 → skillware-0.3.8}/skills/finance/wallet_screening/card.json

@@ -12,10 +12,10 @@
   "ui_schema": {
     "type": "card",
     "fields": [
-      {"key": "summary.address", "label": "Address"},
-      {"key": "summary.sanctioned", "label": "Sanctioned", "type": "status_badge"},
-      {"key": "summary.malicious_interactions_count", "label": "Risky Interactions", "type": "count"},
-      {"key": "summary.pnl_eth", "label": "PnL (ETH)", "type": "currency"}
+      {"key": "metadata.wallet_address", "label": "Address"},
+      {"key": "summary.sanctioned_entity_match", "label": "Sanctioned", "type": "status_badge"},
+      {"key": "summary.malicious_interaction_count", "label": "Risky Interactions", "type": "count"},
+      {"key": "financial_analysis.pnl_eth", "label": "PnL (ETH)", "type": "currency"}
     ]
   }
 }

{skillware-0.3.6 → skillware-0.3.8}/skills/finance/wallet_screening/instructions.md

@@ -1,6 +1,6 @@
 # Wallet Screening Skill Instructions
 
-You are equipped with the `wallet_screening` skill. This tool allows you to perform due diligence on Ethereum addresses.
+You are equipped with the `finance/wallet_screening` skill. This tool allows you to perform due diligence on Ethereum addresses.
 
 ## When to use
 Use this skill when the user:
@@ -13,10 +13,10 @@ Use this skill when the user:
 The tool returns a JSON object. You should summarize this for the user in a professional, "Compliance Officer" tone.
 
 ### Key Fields to Check:
-1.  **`summary.sanctioned` (Boolean)**: If `true`, this is CRITICAL. Report the `sanctions_hits` immediately.
-2.  **`summary.malicious_interactions` (Integer)**: If > 0, the wallet has touched bad actors. List the `malicious_contracts_check.matches`.
-3.  **`summary.pnl`**: Profit and Loss. Useful for determining if it's a profitable trader or a victim.
-4.  **`counterparty_analysis`**: Who are they sending money to?
+1.  **`summary.sanctioned_entity_match` (Boolean)**: If `true`, this is CRITICAL. Report the `risk_details.sanctions_hits` immediately.
+2.  **`summary.malicious_interaction_count` (Integer)**: If > 0, the wallet has touched bad actors. List the `risk_details.malicious_interactions`.
+3.  **`financial_analysis.pnl_eth` / `pnl_usd`**: Profit and Loss. Useful for determining if it's a profitable trader or a victim.
+4.  **`network_analysis.top_10_counterparties`**: Who are they sending money to?
 
 ## Safety Protocol
 *   If a wallet is **Sanctioned**: severe warning. "⚠️ WARNING: This wallet appears on the following sanctions lists..."

skillware-0.3.8/skills/wellness/mental_coach/__init__.py

@@ -0,0 +1,3 @@
+from .skill import MentalCoachSkill
+
+__all__ = ["MentalCoachSkill"]

skillware-0.3.8/skills/wellness/mental_coach/card.json

@@ -0,0 +1,25 @@
+{
+  "name": "Mental Coach",
+  "description": "Wellness coaching guardrail with crisis triage and grounded KB retrieval.",
+  "issuer": {
+    "name": "Masa",
+    "email": "masa88keith@gmail.com",
+    "github": "mrmasa88",
+    "org": "AO"
+  },
+  "icon": "heart",
+  "color": "blue",
+  "ui_schema": {
+    "type": "card",
+    "fields": [
+      {
+        "key": "policy_status",
+        "label": "Policy Status"
+      },
+      {
+        "key": "scope",
+        "label": "Scope"
+      }
+    ]
+  }
+}

skillware-0.3.8/skills/wellness/mental_coach/constraints.py

@@ -0,0 +1,93 @@
+"""Load and apply hard constraints from kb/hard_constraints.yaml."""
+
+from __future__ import annotations
+
+import os
+import re
+from functools import lru_cache
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+_CONSTRAINTS_PATH = os.path.join(
+    os.path.dirname(__file__), "kb", "hard_constraints.yaml"
+)
+
+CLINICAL_PATTERNS: Dict[str, List[str]] = {
+    "no_diagnosis": [
+        r"\bdiagnos(e|is|ing)\b",
+        r"\bdo i have (depression|anxiety|bipolar|adhd|ptsd|ocd)\b",
+        r"\bwhat (disorder|condition|illness) do i have\b",
+        r"\bam i (depressed|bipolar|schizophrenic)\b",
+    ],
+    "no_medication_advice": [
+        r"\b(should i|can i) (take|stop|start) (my )?(medication|meds|antidepressant)\b",
+        r"\bwhat medication\b",
+        r"\bwhat dose\b",
+        r"\bprescribe\b",
+        r"\b(increase|decrease) my (dose|dosage)\b",
+    ],
+    "no_clinical_interpretation": [
+        r"\binterpret my (lab|blood test|test results)\b",
+        r"\bwhat do my results mean\b",
+        r"\bclinical record\b",
+    ],
+}
+
+INJECTION_PATTERNS = [
+    r"ignore (your|all|previous) (rules|instructions|constraints)",
+    r"disregard (your|the) (policy|safety|guidelines)",
+    r"pretend you are (a )?(doctor|therapist|psychiatrist)",
+    r"jailbreak",
+    r"bypass (your|the) (rules|safety|filter)",
+]
+
+
+@lru_cache(maxsize=1)
+def load_constraints_config() -> Dict[str, Any]:
+    with open(_CONSTRAINTS_PATH, "r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    return data if isinstance(data, dict) else {}
+
+
+def get_disclaimers(kind: str = "default") -> List[str]:
+    config = load_constraints_config()
+    disclaimers = config.get("disclaimers_required", {})
+    items = disclaimers.get(kind, disclaimers.get("default", []))
+    return list(items) if isinstance(items, list) else []
+
+
+def detect_clinical_violation(text: str) -> Optional[str]:
+    normalized = text.lower()
+    for constraint_id, patterns in CLINICAL_PATTERNS.items():
+        for pattern in patterns:
+            if re.search(pattern, normalized):
+                return constraint_id
+    return None
+
+
+def detect_injection_attempt(text: str) -> bool:
+    normalized = text.lower()
+    return any(re.search(pattern, normalized) for pattern in INJECTION_PATTERNS)
+
+
+def get_playbook_entry(decision: str) -> Dict[str, Any]:
+    config = load_constraints_config()
+    playbook = config.get("escalation_playbook", {})
+    key = {
+        "ESCALATE": "on_escalate",
+        "CAUTION": "on_caution",
+        "OK": "on_ok",
+    }.get(decision, "on_ok")
+    entry = playbook.get(key, {})
+    return entry if isinstance(entry, dict) else {}
+
+
+def list_hard_constraint_ids() -> List[str]:
+    config = load_constraints_config()
+    items = config.get("hard_constraints", [])
+    ids: List[str] = []
+    for item in items:
+        if isinstance(item, dict) and item.get("id"):
+            ids.append(str(item["id"]))
+    return ids

skillware-0.3.8/skills/wellness/mental_coach/crisis_gate.py

@@ -0,0 +1,175 @@
+"""Deterministic crisis gate — runs before retrieval, no LLM dependency."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from typing import Dict, List, Sequence, Tuple
+
+# Minimal conservative signal sets (intent-level, not exhaustive lexicons).
+CRISIS_SIGNALS: Dict[str, Sequence[str]] = {
+    "suicidal_ideation": (
+        "kill myself",
+        "end my life",
+        "want to die",
+        "suicidal",
+        "not want to live",
+        "better off dead",
+        "end it all",
+    ),
+    "self_harm": (
+        "hurt myself",
+        "harm myself",
+        "cut myself",
+        "self harm",
+        "self-harm",
+    ),
+    "harm_to_others": (
+        "hurt someone",
+        "kill him",
+        "kill her",
+        "kill them",
+        "harm others",
+        "going to hurt",
+    ),
+    "abuse_or_violence": (
+        "being abused",
+        "he hits me",
+        "she hits me",
+        "sexually assaulted",
+        "domestic violence",
+        "partner hurts me",
+    ),
+    "acute_medical_emergency": (
+        "can't breathe",
+        "cannot breathe",
+        "chest pain",
+        "overdose",
+        "heart attack",
+        "having a stroke",
+    ),
+    "severe_acute_distress": (
+        "can't cope",
+        "cannot cope",
+        "falling apart",
+        "panic attack",
+        "overwhelmed can't function",
+        "completely overwhelmed",
+    ),
+}
+
+CATEGORY_ACTION = {
+    "suicidal_ideation": "ESCALATE",
+    "self_harm": "ESCALATE",
+    "harm_to_others": "ESCALATE",
+    "abuse_or_violence": "ESCALATE",
+    "acute_medical_emergency": "ESCALATE",
+    "severe_acute_distress": "CAUTION",
+}
+
+NEGATION_PREFIXES = (
+    "don't ",
+    "do not ",
+    "never ",
+    "not going to ",
+    "won't ",
+    "wouldn't ",
+)
+
+CJK_RE = re.compile(r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uac00-\ud7af]")
+NON_ASCII_RE = re.compile(r"[^\x00-\x7F]")
+
+
+@dataclass
+class LanguageAssessment:
+    is_english: bool
+    non_english: bool
+    reason: str = ""
+
+
+@dataclass
+class GateResult:
+    policy_status: str
+    crisis_categories: List[str] = field(default_factory=list)
+    ambiguous: bool = False
+
+
+def normalize_text(text: str) -> str:
+    normalized = unicodedata.normalize("NFKC", text or "")
+    normalized = re.sub(r"\s+", " ", normalized).strip().lower()
+    return normalized
+
+
+def assess_language(text: str) -> LanguageAssessment:
+    if not text.strip():
+        return LanguageAssessment(is_english=True, non_english=False)
+
+    if CJK_RE.search(text):
+        return LanguageAssessment(
+            is_english=False,
+            non_english=True,
+            reason="CJK characters detected; v0.1 is EN-first.",
+        )
+
+    non_ascii = len(NON_ASCII_RE.findall(text))
+    if non_ascii >= 8 or (len(text) > 0 and non_ascii / len(text) > 0.15):
+        return LanguageAssessment(
+            is_english=False,
+            non_english=True,
+            reason="High non-ASCII ratio; v0.1 is EN-first.",
+        )
+
+    return LanguageAssessment(is_english=True, non_english=False)
+
+
+def _has_negation_before(text: str, index: int) -> bool:
+    window = text[max(0, index - 48) : index]
+    return any(prefix in window for prefix in NEGATION_PREFIXES)
+
+
+def _match_signals(normalized: str) -> Tuple[List[str], bool]:
+    matched: List[str] = []
+    ambiguous = False
+    for category, signals in CRISIS_SIGNALS.items():
+        for signal in signals:
+            start = 0
+            while True:
+                idx = normalized.find(signal, start)
+                if idx < 0:
+                    break
+                if _has_negation_before(normalized, idx):
+                    ambiguous = True
+                else:
+                    matched.append(category)
+                start = idx + len(signal)
+    # Preserve order, dedupe
+    seen = set()
+    ordered: List[str] = []
+    for cat in matched:
+        if cat not in seen:
+            ordered.append(cat)
+            seen.add(cat)
+    return ordered, ambiguous
+
+
+def _resolve_policy(categories: Sequence[str], ambiguous: bool) -> str:
+    if categories:
+        if any(CATEGORY_ACTION.get(c) == "ESCALATE" for c in categories):
+            return "ESCALATE"
+        if any(CATEGORY_ACTION.get(c) == "CAUTION" for c in categories):
+            return "CAUTION"
+    if ambiguous:
+        return "CAUTION"
+    return "OK"
+
+
+def evaluate_crisis_gate(user_prompt: str) -> GateResult:
+    normalized = normalize_text(user_prompt)
+    categories, ambiguous = _match_signals(normalized)
+    policy_status = _resolve_policy(categories, ambiguous)
+    return GateResult(
+        policy_status=policy_status,
+        crisis_categories=categories,
+        ambiguous=ambiguous and policy_status != "ESCALATE",
+    )

skillware-0.3.8/skills/wellness/mental_coach/instructions.md

@@ -0,0 +1,37 @@
+# Operational Instructions: Mental Coach
+
+You are an agent equipped with the `wellness/mental_coach` skill.
+
+## When to use this skill
+
+- Before responding to wellness, stress, coping, or psychoeducation requests.
+- When you need deterministic crisis triage and non-clinical scope enforcement.
+- When you must ground coaching guidance in cited KB chunks with required disclaimers.
+
+## What this skill does
+
+1. Runs a deterministic crisis gate first (no LLM) and escalates on danger signals.
+2. Blocks clinical requests (diagnosis, medication advice, clinical interpretation).
+3. Retrieves grounded coaching chunks from the embedded public KB when safe to coach.
+4. Optionally runs a scope evaluator (Gemini) when `run_evaluator` is enabled.
+
+## How to interpret output
+
+- `policy_status: ESCALATE` — stop coaching; use `final_context_for_agent` and resources only.
+- `policy_status: BLOCKED` — decline the clinical request; offer non-clinical alternatives.
+- `policy_status: CAUTION` — proceed gently; include disclaimers and consider resources.
+- `policy_status: OK` — coaching path; follow retrieved citations exactly.
+
+Always surface `disclaimers_required` verbatim in the user-facing reply.
+
+## Limitations
+
+- Supportive coaching and psychoeducation only; not emergency services or licensed care.
+- v0.1 is English-first; non-English input is routed to CAUTION with resources.
+- Optional evaluator requires `GOOGLE_API_KEY` when enabled.
+
+## Example uses
+
+- User: "I feel stressed at work and need coping strategies." -> coaching retrieval path.
+- User: "Can you diagnose my anxiety?" -> blocked clinical path.
+- User: "I want to hurt myself." -> crisis escalation path (no coaching content).