skillware 0.3.8__tar.gz → 0.3.9__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.8
+Version: 0.3.9
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License

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

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

{skillware-0.3.8 → skillware-0.3.9}/skillware/cli.py

@@ -5,7 +5,9 @@ import sys
 import yaml
 from collections import defaultdict
 from pathlib import Path
-from typing import List, Dict, Any, Optional, Tuple
+from typing import List, Dict, Any, Optional, Tuple, Union
+
+import requests
 
 from rich.table import Table
 from rich.console import Console
@@ -29,6 +31,13 @@ _EXAMPLES_README_REL = Path("examples") / "README.md"
 _PARENT_WALK_LIMIT = 6
 _SKILL_ID_PATTERN = re.compile(r"`([\w-]+/[\w-]+)`")
 _EXAMPLES_GITHUB_BLOB_BASE = "https://github.com/ARPAHLS/skillware/blob/main/examples"
+_EXAMPLES_README_GITHUB_URL = (
+    "https://github.com/ARPAHLS/skillware/blob/main/examples/README.md"
+)
+_EXAMPLES_README_RAW_URL = (
+    "https://raw.githubusercontent.com/ARPAHLS/skillware/main/examples/README.md"
+)
+_EXAMPLES_INDEX_SOURCE = Union[Path, str]
 
 
 def _flatten_table_cell(text: str, max_len: int = 80) -> str:
@@ -39,10 +48,12 @@ def _flatten_table_cell(text: str, max_len: int = 80) -> str:
     return cleaned
 
 
-def _examples_readme_display_path(readme_path: Path) -> str:
-    """Prefer a short relative path in CLI output."""
+def _examples_readme_display_path(source: _EXAMPLES_INDEX_SOURCE) -> str:
+    """Prefer a short relative path in CLI output; GitHub URL when loaded remotely."""
+    if isinstance(source, str):
+        return source
     try:
-        return readme_path.relative_to(Path.cwd()).as_posix()
+        return source.relative_to(Path.cwd()).as_posix()
     except ValueError:
         return "examples/README.md"
 
@@ -53,7 +64,7 @@ def _example_github_url(script: str) -> str:
 
 
 def _examples_readme_path() -> Optional[Path]:
-    """Resolve examples/README.md for editable checkout or bundled install."""
+    """Resolve a local examples/README.md from checkout or cwd walk."""
     candidates: List[Path] = []
 
     package_root = Path(__file__).resolve().parent.parent
@@ -75,9 +86,18 @@ def _examples_readme_path() -> Optional[Path]:
     return None
 
 
-def _parse_examples_index(readme_path: Path) -> List[Dict[str, Any]]:
-    """Parse the Runnable Scripts table from examples/README.md."""
-    text = readme_path.read_text(encoding="utf-8")
+def _fetch_examples_readme_from_github() -> Optional[str]:
+    """Download examples/README.md from the canonical repo on GitHub."""
+    try:
+        response = requests.get(_EXAMPLES_README_RAW_URL, timeout=10)
+        response.raise_for_status()
+        return response.text
+    except (requests.RequestException, OSError):
+        return None
+
+
+def _parse_examples_index_text(text: str) -> List[Dict[str, Any]]:
+    """Parse the Runnable Scripts table from examples/README.md content."""
     section_start = text.find("## Runnable Scripts")
     if section_start == -1:
         return []
@@ -112,6 +132,11 @@ def _parse_examples_index(readme_path: Path) -> List[Dict[str, Any]]:
     return rows
 
 
+def _parse_examples_index(readme_path: Path) -> List[Dict[str, Any]]:
+    """Parse the Runnable Scripts table from a local examples/README.md file."""
+    return _parse_examples_index_text(readme_path.read_text(encoding="utf-8"))
+
+
 def _example_counts_by_skill(rows: List[Dict[str, Any]]) -> Dict[str, int]:
     """Map skill ID to indexed script count (multi-skill rows count toward each ID)."""
     counts: Dict[str, int] = defaultdict(int)
@@ -121,11 +146,16 @@ def _example_counts_by_skill(rows: List[Dict[str, Any]]) -> Dict[str, int]:
     return dict(counts)
 
 
-def _load_examples_index() -> Tuple[List[Dict[str, Any]], Optional[Path]]:
+def _load_examples_index() -> Tuple[List[Dict[str, Any]], Optional[_EXAMPLES_INDEX_SOURCE]]:
     readme_path = _examples_readme_path()
-    if readme_path is None:
-        return [], None
-    return _parse_examples_index(readme_path), readme_path
+    if readme_path is not None:
+        return _parse_examples_index_text(readme_path.read_text(encoding="utf-8")), readme_path
+
+    text = _fetch_examples_readme_from_github()
+    if text is not None:
+        return _parse_examples_index_text(text), _EXAMPLES_README_GITHUB_URL
+
+    return [], None
 
 
 def _get_skill_roots(skills_root_override: Optional[Path] = None) -> List[Path]:
@@ -323,10 +353,11 @@ def cmd_list(
 
     example_counts: Dict[str, int] = {}
     if show_examples:
-        rows, readme_path = _load_examples_index()
-        if readme_path is None:
+        rows, readme_source = _load_examples_index()
+        if readme_source is None:
             console.print(
-                "examples/README.md not found; cannot show example counts.",
+                "examples/README.md not found locally or on GitHub; "
+                "cannot show example counts.",
                 style="bold #FF9AA2",
             )
         else:
@@ -373,9 +404,12 @@ def cmd_examples(
     if console is None:
         console = Console()
 
-    rows, readme_path = _load_examples_index()
-    if readme_path is None:
-        console.print("examples/README.md not found.", style="bold #FF9AA2")
+    rows, readme_source = _load_examples_index()
+    if readme_source is None:
+        console.print(
+            "Could not load examples/README.md from the repo or GitHub.",
+            style="bold #FF9AA2",
+        )
         return 1
 
     if skill_id:
@@ -391,7 +425,7 @@ def cmd_examples(
         if not rows:
             console.print(
                 f"No indexed examples for '{skill_id}'. "
-                f"See {_examples_readme_display_path(readme_path)} for the full inventory.",
+                f"See {_examples_readme_display_path(readme_source)} for the full inventory.",
                 style="bold #FF9AA2",
             )
             return 1
@@ -423,7 +457,7 @@ def cmd_examples(
 
     console.print(table)
     console.print(
-        f"Full notes: {_examples_readme_display_path(readme_path)}",
+        f"Full notes: {_examples_readme_display_path(readme_source)}",
         style="dim",
     )
     return 0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.8
+Version: 0.3.9
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License

{skillware-0.3.8 → skillware-0.3.9}/skillware.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
-examples/README.md
 skills/__init__.py
 skills/compliance/__init__.py
 skills/compliance/mica_module/__init__.py

{skillware-0.3.8 → skillware-0.3.9}/tests/test_cli.py

@@ -2,6 +2,7 @@ from skillware.cli import (
     _discover_skills,
     _resolve_pytest_targets,
     _parse_examples_index,
+    _load_examples_index,
     _example_counts_by_skill,
     _example_github_url,
     cmd_list,
@@ -583,6 +584,46 @@ def test_cmd_examples_unknown_skill_returns_nonzero(examples_readme):
     assert rc == 1
 
 
+def test_load_examples_index_prefers_local_readme(examples_readme):
+    rows, source = _load_examples_index()
+    assert len(rows) == 2
+    assert source == examples_readme
+
+
+def test_load_examples_index_github_fallback(monkeypatch):
+    monkeypatch.setattr("skillware.cli._examples_readme_path", lambda: None)
+
+    class FakeResponse:
+        text = SAMPLE_EXAMPLES_README
+
+        def raise_for_status(self):
+            return None
+
+    monkeypatch.setattr(
+        "skillware.cli.requests.get",
+        lambda url, timeout: FakeResponse(),
+    )
+
+    rows, source = _load_examples_index()
+    assert len(rows) == 2
+    assert source == (
+        "https://github.com/ARPAHLS/skillware/blob/main/examples/README.md"
+    )
+
+
+def test_load_examples_index_github_failure(monkeypatch):
+    monkeypatch.setattr("skillware.cli._examples_readme_path", lambda: None)
+
+    def raise_error(url, timeout):
+        raise OSError("offline")
+
+    monkeypatch.setattr("skillware.cli.requests.get", raise_error)
+
+    rows, source = _load_examples_index()
+    assert rows == []
+    assert source is None
+
+
 def test_main_examples_subcommand_exits_with_cmd_examples_code(monkeypatch):
     import sys
     from skillware.cli import main

skillware-0.3.8/examples/README.md

@@ -1,61 +0,0 @@
-# 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.