skillware 0.2.4__tar.gz → 0.2.6__tar.gz

{skillware-0.2.4 → skillware-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.2.4
+Version: 0.2.6
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logic Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -38,6 +38,7 @@ Requires-Dist: pyyaml
 Requires-Dist: anthropic
 Requires-Dist: google-generativeai
 Requires-Dist: pymupdf
+Requires-Dist: beautifulsoup4
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
@@ -102,7 +103,8 @@ Skillware/
 │       └── skill_name/         # The Skill bundle
 │           ├── manifest.yaml   # Definition, schema, and constitution
 │           ├── skill.py        # Executable Python logic
-│           └── instructions.md # Cognitive map for the LLM
+│           ├── instructions.md # Cognitive map for the LLM
+│           └── test_skill.py   # Unit tests & schema validation
 ├── skillware/                  # Core Framework Package
 │   └── core/
 │       ├── base_skill.py       # Abstract Base Class for skills
@@ -172,20 +174,26 @@ print(response.text)
 ## Documentation
 
 *   **[Core Logic & Philosophy](docs/introduction.md)**: Details on how Skillware decouples Logic, Cognition, and Governance.
+*   **[Testing Guidelines](docs/TESTING.md)**: Instructions for validating skills and checking local coverage.
+*   **[Usage guides](docs/usage/README.md)**: Provider adapters and navigation to integration docs.
+*   **[Agent loops](docs/usage/agent_loops.md)**: Shared load, tool-call, and `execute` pattern across providers.
 *   **[Usage Guide: Gemini](docs/usage/gemini.md)**: Integration with Google's GenAI SDK.
 *   **[Usage Guide: Claude](docs/usage/claude.md)**: Integration with Anthropic's SDK.
+*   **[Usage Guide: OpenAI](docs/usage/openai.md)**: Integration with OpenAI Chat Completions tool calling.
+*   **[Usage Guide: DeepSeek](docs/usage/deepseek.md)**: Integration with the DeepSeek API via `to_deepseek_tool()`.
 *   **[Usage Guide: Ollama](docs/usage/ollama.md)**: Native integration for local models via Ollama.
+*   **[API Keys for Skills](docs/usage/api_keys.md)**: Environment variables, cloud/CI setup, and security for skills that call external APIs.
 *   **[Skill Library](docs/skills/README.md)**: Available capabilities.
 
 ## Contributing
 
-We are building the "App Store" for Agents and require professional, robust, and safe skills.
+We are building the "App Store" for Agents and require professional, robust, and safe skills. We welcome contributions to the skill registry, documentation, tests, and core framework.
 
-We actively encourage both humans and autonomous agents to contribute to this repository!
-
-* Please read our **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** which outlines our strict expectations for deterministic outputs, zero LLM code generation, and safety boundaries.
-* When submitting skills, our new **Agent-Friendly Pull Request Template** provides a checklist to ensure your logic aligns natively with `loader.py` and `base_skill.py`.
-* Please also review **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed guidelines on folder structure and schema definitions.
+* **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution types, skill standard, pull request process, and navigation to all contributor docs.
+* **[Agent Contribution Workflow](docs/contributing/ai_native_workflow.md)** — Workflow for AI agents contributing to the repository (operators supervise).
+* **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** — Deterministic outputs, safety boundaries, and acceptable use of skills.
+* **[TESTING.md](docs/TESTING.md)** — Local linting and pytest before you open a PR.
+* **[Pull request template](.github/PULL_REQUEST_TEMPLATE.md)** — Checklists for skills, docs, and framework changes (complete only the sections that apply).
 
 ## Comparison
 

{skillware-0.2.4 → skillware-0.2.6}/README.md

@@ -55,7 +55,8 @@ Skillware/
 │       └── skill_name/         # The Skill bundle
 │           ├── manifest.yaml   # Definition, schema, and constitution
 │           ├── skill.py        # Executable Python logic
-│           └── instructions.md # Cognitive map for the LLM
+│           ├── instructions.md # Cognitive map for the LLM
+│           └── test_skill.py   # Unit tests & schema validation
 ├── skillware/                  # Core Framework Package
 │   └── core/
 │       ├── base_skill.py       # Abstract Base Class for skills
@@ -125,20 +126,26 @@ print(response.text)
 ## Documentation
 
 *   **[Core Logic & Philosophy](docs/introduction.md)**: Details on how Skillware decouples Logic, Cognition, and Governance.
+*   **[Testing Guidelines](docs/TESTING.md)**: Instructions for validating skills and checking local coverage.
+*   **[Usage guides](docs/usage/README.md)**: Provider adapters and navigation to integration docs.
+*   **[Agent loops](docs/usage/agent_loops.md)**: Shared load, tool-call, and `execute` pattern across providers.
 *   **[Usage Guide: Gemini](docs/usage/gemini.md)**: Integration with Google's GenAI SDK.
 *   **[Usage Guide: Claude](docs/usage/claude.md)**: Integration with Anthropic's SDK.
+*   **[Usage Guide: OpenAI](docs/usage/openai.md)**: Integration with OpenAI Chat Completions tool calling.
+*   **[Usage Guide: DeepSeek](docs/usage/deepseek.md)**: Integration with the DeepSeek API via `to_deepseek_tool()`.
 *   **[Usage Guide: Ollama](docs/usage/ollama.md)**: Native integration for local models via Ollama.
+*   **[API Keys for Skills](docs/usage/api_keys.md)**: Environment variables, cloud/CI setup, and security for skills that call external APIs.
 *   **[Skill Library](docs/skills/README.md)**: Available capabilities.
 
 ## Contributing
 
-We are building the "App Store" for Agents and require professional, robust, and safe skills.
+We are building the "App Store" for Agents and require professional, robust, and safe skills. We welcome contributions to the skill registry, documentation, tests, and core framework.
 
-We actively encourage both humans and autonomous agents to contribute to this repository!
-
-* Please read our **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** which outlines our strict expectations for deterministic outputs, zero LLM code generation, and safety boundaries.
-* When submitting skills, our new **Agent-Friendly Pull Request Template** provides a checklist to ensure your logic aligns natively with `loader.py` and `base_skill.py`.
-* Please also review **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed guidelines on folder structure and schema definitions.
+* **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution types, skill standard, pull request process, and navigation to all contributor docs.
+* **[Agent Contribution Workflow](docs/contributing/ai_native_workflow.md)** — Workflow for AI agents contributing to the repository (operators supervise).
+* **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** — Deterministic outputs, safety boundaries, and acceptable use of skills.
+* **[TESTING.md](docs/TESTING.md)** — Local linting and pytest before you open a PR.
+* **[Pull request template](.github/PULL_REQUEST_TEMPLATE.md)** — Checklists for skills, docs, and framework changes (complete only the sections that apply).
 
 ## Comparison
 

{skillware-0.2.4 → skillware-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.2.4"
+version = "0.2.6"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [
@@ -23,6 +23,7 @@ dependencies = [
     "anthropic",
     "google-generativeai",
     "pymupdf",
+    "beautifulsoup4",
 ]
 requires-python = ">=3.10"
 

skillware-0.2.6/skills/compliance/tos_evaluator/__init__.py

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

skillware-0.2.6/skills/compliance/tos_evaluator/skill.py

@@ -0,0 +1,587 @@
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional
+from urllib.parse import urljoin, urlparse
+from urllib.robotparser import RobotFileParser
+
+import requests
+import yaml
+from bs4 import BeautifulSoup
+from skillware.core.base_skill import BaseSkill
+
+try:
+    import google.generativeai as genai
+except ImportError:  # pragma: no cover - dependency is optional at runtime
+    genai = None
+
+
+class TOSEvaluatorSkill(BaseSkill):
+    """
+    Evaluates whether an automated website action appears permissible based on
+    robots.txt and discovered legal policy pages.
+    """
+
+    WELL_KNOWN_POLICY_PATHS = [
+        "/terms",
+        "/terms-of-service",
+        "/terms-of-use",
+        "/tos",
+        "/legal/terms",
+        "/legal",
+        "/conditions",
+        "/policies/terms",
+        "/acceptable-use",
+        "/aup",
+        "/developer-terms",
+        "/api-terms",
+    ]
+
+    POLICY_KEYWORDS = {
+        "terms": 8,
+        "terms of service": 12,
+        "terms of use": 12,
+        "tos": 6,
+        "legal": 5,
+        "conditions": 4,
+        "user agreement": 8,
+        "acceptable use": 10,
+        "developer terms": 8,
+        "api terms": 10,
+        "api policy": 9,
+        "robots": 3,
+    }
+
+    ACTION_PATTERNS = {
+        "scrape": [r"\bscrap", r"\bextract", r"\bharvest", r"\bcollect data\b"],
+        "crawl": [r"\bcrawl", r"\bspider", r"\bbot\b", r"\bautomated access\b"],
+        "index": [r"\bindex", r"\bsearch engine", r"\barchive", r"\bmirror"],
+        "api_use": [r"\bapi\b", r"\bdeveloper\b", r"\bintegration\b"],
+        "monitor": [r"\bmonitor", r"\bwatch", r"\btrack", r"\bcheck periodically\b"],
+        "download": [r"\bdownload", r"\bexport", r"\bbulk\b"],
+        "automated_access": [r"\bautomation\b", r"\bscript", r"\bprogrammatic\b"],
+    }
+
+    CLAUSE_PATTERNS = [
+        {
+            "label": "hard_block",
+            "severity": "high",
+            "weight": -45,
+            "patterns": [
+                r"may not scrape",
+                r"must not scrape",
+                r"no scraping",
+                r"no crawlers",
+                r"no robots",
+                r"no automated means",
+                r"prohibited automated access",
+                r"automated means.*prohibited",
+                r"harvest.*prohibited",
+                r"crawl.*prohibited",
+            ],
+        },
+        {
+            "label": "soft_caution",
+            "severity": "medium",
+            "weight": -20,
+            "patterns": [
+                r"prior written consent",
+                r"without our permission",
+                r"reasonable rate",
+                r"rate limit",
+                r"commercial use.*restricted",
+                r"access.*subject to",
+                r"must comply with.*api",
+                r"use the api",
+            ],
+        },
+        {
+            "label": "permission",
+            "severity": "low",
+            "weight": 18,
+            "patterns": [
+                r"permitted to access",
+                r"you may use.*api",
+                r"public api",
+                r"developers may access",
+                r"search engines may crawl",
+            ],
+        },
+    ]
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        super().__init__(config)
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "User-Agent": "Skillware-TOS-Evaluator/0.1 (+https://github.com/ARPAHLS/skillware)"
+            }
+        )
+
+    @property
+    def manifest(self) -> Dict[str, Any]:
+        manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
+        if os.path.exists(manifest_path):
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                return yaml.safe_load(f)
+        return {}
+
+    def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        normalized = self._normalize_input(params)
+        if "error" in normalized:
+            return normalized
+
+        robots_assessment = self._evaluate_robots(
+            normalized["origin"], normalized["target_url"], normalized["user_agent"]
+        )
+        policy_candidates = self._discover_policy_pages(
+            normalized["origin"], robots_assessment, normalized["max_terms_pages"]
+        )
+        tos_assessment = self._evaluate_policy_pages(
+            normalized, policy_candidates, normalized["max_terms_pages"]
+        )
+
+        llm_assessment = None
+        if self._should_use_llm(normalized, robots_assessment, tos_assessment):
+            llm_assessment = self._run_llm_evaluator(normalized, tos_assessment)
+
+        return self._build_final_result(
+            normalized,
+            robots_assessment,
+            tos_assessment,
+            llm_assessment,
+            policy_candidates,
+        )
+
+    def _normalize_input(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        target_url = params.get("target_url", "").strip()
+        intended_action = params.get("intended_action", "").strip()
+        if not target_url:
+            return {"error": "target_url is required."}
+        if not intended_action:
+            return {"error": "intended_action is required."}
+
+        parsed = urlparse(target_url)
+        if not parsed.scheme or not parsed.netloc:
+            return {"error": "target_url must be a fully qualified URL."}
+
+        origin = f"{parsed.scheme}://{parsed.netloc}"
+        action_type = self._classify_action(intended_action)
+        user_agent = params.get("user_agent", self.session.headers["User-Agent"])
+
+        return {
+            "target_url": target_url,
+            "intended_action": intended_action,
+            "action_type": action_type,
+            "origin": origin,
+            "path": parsed.path or "/",
+            "user_agent": user_agent,
+            "fetch_mode": params.get("fetch_mode", "lightweight"),
+            "use_llm_evaluator": bool(params.get("use_llm_evaluator", False)),
+            "llm_provider": params.get("llm_provider", "gemini"),
+            "llm_model": params.get("llm_model", "gemini-2.5-flash-lite"),
+            "assume_authenticated_session": bool(
+                params.get("assume_authenticated_session", False)
+            ),
+            "max_terms_pages": max(1, min(int(params.get("max_terms_pages", 5)), 10)),
+        }
+
+    def _classify_action(self, intended_action: str) -> str:
+        lowered = intended_action.lower()
+        for action, patterns in self.ACTION_PATTERNS.items():
+            if any(re.search(pattern, lowered) for pattern in patterns):
+                return action
+        return "automated_access"
+
+    def _evaluate_robots(
+        self, origin: str, target_url: str, user_agent: str
+    ) -> Dict[str, Any]:
+        robots_url = f"{origin}/robots.txt"
+        assessment = {
+            "status": "unavailable",
+            "robots_url": robots_url,
+            "can_fetch": None,
+            "matched_rule": "unknown",
+            "crawl_delay": None,
+            "request_rate": None,
+            "sitemaps": [],
+            "reason": "robots.txt could not be retrieved.",
+        }
+
+        try:
+            response = self.session.get(robots_url, timeout=10)
+            if response.status_code >= 400:
+                assessment["reason"] = f"robots.txt returned HTTP {response.status_code}."
+                return assessment
+
+            parser = RobotFileParser()
+            parser.set_url(robots_url)
+            parser.parse(response.text.splitlines())
+
+            can_fetch = parser.can_fetch(user_agent, target_url)
+            assessment["status"] = "parsed"
+            assessment["can_fetch"] = can_fetch
+            assessment["matched_rule"] = "allowed" if can_fetch else "disallowed"
+            assessment["crawl_delay"] = parser.crawl_delay(user_agent)
+            assessment["request_rate"] = parser.request_rate(user_agent)
+            assessment["sitemaps"] = parser.site_maps() or []
+            assessment["reason"] = (
+                "robots.txt allows the target path."
+                if can_fetch
+                else "robots.txt disallows the target path for the supplied user-agent."
+            )
+            return assessment
+        except requests.RequestException as exc:
+            assessment["reason"] = f"robots.txt request failed: {str(exc)}"
+            return assessment
+
+    def _discover_policy_pages(
+        self, origin: str, robots_assessment: Dict[str, Any], max_terms_pages: int
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        candidates: Dict[str, Dict[str, Any]] = {}
+
+        for path in self.WELL_KNOWN_POLICY_PATHS:
+            url = urljoin(origin, path)
+            score = 50 if "terms" in path or "acceptable" in path else 35
+            candidates[url] = {
+                "url": url,
+                "score": score,
+                "source": "well_known_path",
+                "label": path.strip("/") or "legal",
+            }
+
+        html_pages = [origin]
+        for sitemap_url in robots_assessment.get("sitemaps", [])[:2]:
+            html_pages.append(sitemap_url)
+
+        for url in html_pages:
+            discovered = self._extract_candidate_links(url, origin)
+            for item in discovered:
+                existing = candidates.get(item["url"])
+                if existing:
+                    existing["score"] = max(existing["score"], item["score"])
+                    existing["source"] = f"{existing['source']},{item['source']}"
+                else:
+                    candidates[item["url"]] = item
+
+        ordered = sorted(candidates.values(), key=lambda item: item["score"], reverse=True)
+        return {"candidates": ordered[:max_terms_pages]}
+
+    def _extract_candidate_links(self, page_url: str, origin: str) -> List[Dict[str, Any]]:
+        links: List[Dict[str, Any]] = []
+        response = self._safe_get(page_url, timeout=10)
+        if not response or "html" not in response.headers.get("Content-Type", "").lower():
+            return links
+
+        soup = BeautifulSoup(response.text[:300000], "html.parser")
+        for anchor in soup.find_all("a", href=True):
+            href = anchor.get("href", "").strip()
+            text = " ".join(anchor.stripped_strings).strip().lower()
+            if not href:
+                continue
+
+            absolute = urljoin(page_url, href)
+            parsed = urlparse(absolute)
+            if not parsed.scheme.startswith("http"):
+                continue
+            if f"{parsed.scheme}://{parsed.netloc}" != origin:
+                continue
+
+            score = self._score_policy_link(absolute.lower(), text)
+            if score <= 0:
+                continue
+
+            links.append(
+                {
+                    "url": absolute,
+                    "score": score,
+                    "source": "link_discovery",
+                    "label": text or parsed.path,
+                }
+            )
+
+        return links
+
+    def _score_policy_link(self, href: str, text: str) -> int:
+        combined = f"{href} {text}".lower()
+        score = 0
+        for keyword, weight in self.POLICY_KEYWORDS.items():
+            if keyword in combined:
+                score += weight
+        return score
+
+    def _evaluate_policy_pages(
+        self,
+        normalized: Dict[str, Any],
+        policy_candidates: Dict[str, List[Dict[str, Any]]],
+        max_terms_pages: int,
+    ) -> Dict[str, Any]:
+        pages_evaluated = []
+        clause_hits = []
+
+        for candidate in policy_candidates.get("candidates", [])[:max_terms_pages]:
+            url = candidate["url"]
+            response = self._safe_get(url, timeout=12)
+            if not response:
+                continue
+
+            content_type = response.headers.get("Content-Type", "").lower()
+            if "html" not in content_type:
+                pages_evaluated.append(
+                    {
+                        "url": url,
+                        "status": "skipped",
+                        "reason": f"Unsupported content type: {content_type or 'unknown'}",
+                    }
+                )
+                continue
+
+            extracted_sections = self._extract_policy_sections(response.text)
+            page_hits = self._score_policy_sections(
+                normalized["action_type"], extracted_sections, url
+            )
+            clause_hits.extend(page_hits)
+            pages_evaluated.append(
+                {
+                    "url": url,
+                    "status": "parsed",
+                    "candidate_score": candidate["score"],
+                    "matched_clauses": len(page_hits),
+                }
+            )
+
+        clause_hits.sort(key=lambda item: abs(item["score_delta"]), reverse=True)
+        aggregate_score = sum(item["score_delta"] for item in clause_hits)
+        if not pages_evaluated:
+            status = "insufficient_evidence"
+            summary = "No candidate Terms or policy pages could be parsed."
+        elif any(item["classification"] == "hard_block" for item in clause_hits):
+            status = "blocked"
+            summary = "Discovered policy text contains an explicit restriction on the requested automated behavior."
+        elif aggregate_score <= -20:
+            status = "caution"
+            summary = "Discovered policy text suggests restrictions or conditions on the requested automated behavior."
+        elif aggregate_score > 0:
+            status = "allowed"
+            summary = "Discovered policy text includes language that appears permissive for the requested behavior."
+        else:
+            status = "insufficient_evidence"
+            summary = "Policy pages were found, but none produced strong action-specific evidence."
+
+        return {
+            "status": status,
+            "summary": summary,
+            "pages_evaluated": pages_evaluated,
+            "matched_clauses": clause_hits[:10],
+            "aggregate_score": aggregate_score,
+        }
+
+    def _extract_policy_sections(self, html: str) -> List[Dict[str, str]]:
+        soup = BeautifulSoup(html[:400000], "html.parser")
+        for tag in soup(["script", "style", "noscript", "svg"]):
+            tag.decompose()
+
+        body = soup.body or soup
+        sections: List[Dict[str, str]] = []
+        current_heading = "General"
+
+        for element in body.find_all(["h1", "h2", "h3", "p", "li"]):
+            text = " ".join(element.stripped_strings)
+            text = re.sub(r"\s+", " ", text).strip()
+            if not text or len(text) < 20:
+                continue
+
+            if element.name in {"h1", "h2", "h3"}:
+                current_heading = text[:160]
+                continue
+
+            sections.append({"heading": current_heading, "text": text[:1200]})
+
+        return sections[:200]
+
+    def _score_policy_sections(
+        self, action_type: str, sections: List[Dict[str, str]], page_url: str
+    ) -> List[Dict[str, Any]]:
+        hits = []
+        action_relevance_patterns = self.ACTION_PATTERNS.get(action_type, [])
+        for section in sections:
+            text_lower = section["text"].lower()
+            heading_lower = section["heading"].lower()
+            combined = f"{heading_lower} {text_lower}"
+
+            if action_relevance_patterns and not any(
+                re.search(pattern, combined) for pattern in action_relevance_patterns
+            ):
+                generic_automation = re.search(
+                    r"automated|bot|crawl|scrap|harvest|api|programmatic", combined
+                )
+                if not generic_automation:
+                    continue
+
+            for clause in self.CLAUSE_PATTERNS:
+                for pattern in clause["patterns"]:
+                    if re.search(pattern, combined):
+                        hits.append(
+                            {
+                                "url": page_url,
+                                "heading": section["heading"],
+                                "snippet": section["text"],
+                                "classification": clause["label"],
+                                "severity": clause["severity"],
+                                "score_delta": clause["weight"],
+                            }
+                        )
+                        break
+
+        return hits
+
+    def _should_use_llm(
+        self,
+        normalized: Dict[str, Any],
+        robots_assessment: Dict[str, Any],
+        tos_assessment: Dict[str, Any],
+    ) -> bool:
+        if not normalized.get("use_llm_evaluator"):
+            return False
+        if tos_assessment["status"] in {"blocked", "allowed"}:
+            return False
+        if robots_assessment.get("can_fetch") is False:
+            return False
+        return bool(tos_assessment.get("matched_clauses") or tos_assessment["status"] == "caution")
+
+    def _run_llm_evaluator(
+        self, normalized: Dict[str, Any], tos_assessment: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        provider = normalized["llm_provider"].lower()
+        if provider != "gemini":
+            return {
+                "status": "skipped",
+                "reason": f"Unsupported llm_provider '{normalized['llm_provider']}'.",
+            }
+        if genai is None:
+            return {"status": "skipped", "reason": "google-generativeai is not installed."}
+
+        api_key = os.environ.get("GOOGLE_API_KEY")
+        if not api_key:
+            return {"status": "skipped", "reason": "GOOGLE_API_KEY is not configured."}
+
+        genai.configure(api_key=api_key)
+        prompt = {
+            "target_url": normalized["target_url"],
+            "intended_action": normalized["intended_action"],
+            "action_type": normalized["action_type"],
+            "matched_clauses": tos_assessment.get("matched_clauses", [])[:6],
+            "task": (
+                "Classify whether these policy snippets forbid, allow, or condition "
+                "the requested action. Return strict JSON with keys: "
+                "verdict, confidence_score, rationale."
+            ),
+        }
+
+        try:
+            model = genai.GenerativeModel(normalized["llm_model"])
+            response = model.generate_content(
+                json.dumps(prompt, ensure_ascii=True),
+                generation_config=genai.GenerationConfig(
+                    response_mime_type="application/json", temperature=0.0
+                ),
+            )
+            parsed = json.loads(response.text)
+            return {
+                "status": "used",
+                "provider": provider,
+                "model": normalized["llm_model"],
+                "verdict": parsed.get("verdict", "CAUTION"),
+                "confidence_score": float(parsed.get("confidence_score", 0.5)),
+                "rationale": parsed.get("rationale", "No rationale returned."),
+            }
+        except Exception as exc:
+            return {"status": "error", "reason": f"LLM evaluator failed: {str(exc)}"}
+
+    def _build_final_result(
+        self,
+        normalized: Dict[str, Any],
+        robots_assessment: Dict[str, Any],
+        tos_assessment: Dict[str, Any],
+        llm_assessment: Optional[Dict[str, Any]],
+        policy_candidates: Dict[str, List[Dict[str, Any]]],
+    ) -> Dict[str, Any]:
+        verdict = "INSUFFICIENT_EVIDENCE"
+        confidence_score = 0.35
+        reason = "Insufficient policy evidence to safely approve the requested action."
+        recommended_next_step = "Review the discovered policy pages manually before proceeding."
+
+        if robots_assessment.get("can_fetch") is False:
+            verdict = "UNSAFE"
+            confidence_score = 0.98
+            reason = robots_assessment["reason"]
+            recommended_next_step = (
+                "Do not automate access to this path unless you have explicit permission."
+            )
+        elif tos_assessment["status"] == "blocked":
+            verdict = "UNSAFE"
+            confidence_score = 0.9
+            reason = tos_assessment["summary"]
+            recommended_next_step = "Avoid the requested action or obtain explicit written permission."
+        elif tos_assessment["status"] == "caution":
+            verdict = "CAUTION"
+            confidence_score = 0.65
+            reason = tos_assessment["summary"]
+            recommended_next_step = "Prefer an official API or documented integration path if one exists."
+        elif tos_assessment["status"] == "allowed" and robots_assessment.get("can_fetch") is not False:
+            verdict = "SAFE"
+            confidence_score = 0.72
+            reason = tos_assessment["summary"]
+            recommended_next_step = "Proceed conservatively and continue honoring crawl delays and rate limits."
+
+        if llm_assessment and llm_assessment.get("status") == "used":
+            verdict = llm_assessment.get("verdict", verdict)
+            confidence_score = max(
+                confidence_score,
+                llm_assessment.get("confidence_score", confidence_score),
+            )
+            reason = llm_assessment.get("rationale", reason)
+
+        evidence = []
+        if robots_assessment.get("reason"):
+            evidence.append(
+                {
+                    "source": robots_assessment.get("robots_url"),
+                    "type": "robots",
+                    "snippet": robots_assessment["reason"],
+                }
+            )
+        for clause in tos_assessment.get("matched_clauses", [])[:5]:
+            evidence.append(
+                {
+                    "source": clause["url"],
+                    "type": clause["classification"],
+                    "heading": clause["heading"],
+                    "snippet": clause["snippet"],
+                }
+            )
+
+        return {
+            "is_safe_to_proceed": verdict == "SAFE",
+            "confidence_score": round(float(confidence_score), 2),
+            "verdict": verdict,
+            "reason": reason,
+            "recommended_next_step": recommended_next_step,
+            "action_type": normalized["action_type"],
+            "robots_assessment": robots_assessment,
+            "tos_assessment": tos_assessment,
+            "llm_assessment": llm_assessment or {"status": "not_used"},
+            "discovered_policy_urls": {
+                "candidates": [item["url"] for item in policy_candidates.get("candidates", [])]
+            },
+            "evidence": evidence,
+        }
+
+    def _safe_get(self, url: str, timeout: int = 10) -> Optional[requests.Response]:
+        try:
+            response = self.session.get(url, timeout=timeout, allow_redirects=True)
+            if response.status_code >= 400:
+                return None
+            return response
+        except requests.RequestException:
+            return None

skillware-0.2.6/skills/compliance/tos_evaluator/test_skill.py

@@ -0,0 +1,30 @@
+import os
+
+import pytest
+import yaml
+
+from .skill import TOSEvaluatorSkill
+
+
+@pytest.fixture
+def skill():
+    return TOSEvaluatorSkill()
+
+
+@pytest.fixture
+def manifest():
+    manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
+    with open(manifest_path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def test_skill_manifest_consistency(skill, manifest):
+    skill_manifest = skill.manifest
+    assert skill_manifest["name"] == manifest["name"]
+    assert skill_manifest["version"] == manifest["version"]
+
+
+def test_skill_execution_requires_inputs(skill):
+    result = skill.execute({})
+    assert "error" in result
+    assert "target_url" in result["error"]

{skillware-0.2.4 → skillware-0.2.6}/skillware/core/loader.py

@@ -1,4 +1,5 @@
 import os
+import re
 import yaml
 import json
 import importlib.util
@@ -126,6 +127,69 @@ class SkillLoader:
 
         return {"name": name, "description": description, "input_schema": parameters}
 
+    @staticmethod
+    def _sanitize_function_tool_name(name: str) -> str:
+        """
+        Normalizes manifest tool IDs for OpenAI-compatible function-calling APIs.
+        Allows letters, digits, underscores, and hyphens (max 64 characters).
+        """
+        if not name or not str(name).strip():
+            return "unknown_tool"
+        safe = re.sub(r"[^a-zA-Z0-9_-]", "_", str(name).replace("/", "_"))
+        safe = re.sub(r"_+", "_", safe).strip("_")
+        if not safe:
+            return "unknown_tool"
+        return safe[:64]
+
+    @staticmethod
+    def _sanitize_openai_tool_name(name: str) -> str:
+        return SkillLoader._sanitize_function_tool_name(name)
+
+    @staticmethod
+    def _sanitize_deepseek_tool_name(name: str) -> str:
+        return SkillLoader._sanitize_function_tool_name(name)
+
+    @staticmethod
+    def to_openai_tool(skill_bundle: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Converts a skill manifest to an OpenAI Chat Completions tool definition.
+        See: https://platform.openai.com/docs/guides/function-calling
+        """
+        manifest = skill_bundle.get("manifest", {})
+        raw_name = manifest.get("name", "unknown_tool")
+        description = manifest.get("description", "")
+        parameters = manifest.get("parameters", {})
+
+        return {
+            "type": "function",
+            "function": {
+                "name": SkillLoader._sanitize_openai_tool_name(raw_name),
+                "description": description,
+                "parameters": parameters,
+            },
+        }
+
+    @staticmethod
+    def to_deepseek_tool(skill_bundle: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Converts a skill manifest to a DeepSeek API tool definition.
+        DeepSeek uses an OpenAI-compatible tools schema; this adapter is separate from
+        to_openai_tool() by design. See: https://api-docs.deepseek.com/
+        """
+        manifest = skill_bundle.get("manifest", {})
+        raw_name = manifest.get("name", "unknown_tool")
+        description = manifest.get("description", "")
+        parameters = manifest.get("parameters", {})
+
+        return {
+            "type": "function",
+            "function": {
+                "name": SkillLoader._sanitize_deepseek_tool_name(raw_name),
+                "description": description,
+                "parameters": parameters,
+            },
+        }
+
     @staticmethod
     def to_ollama_prompt(skill_bundle: Dict[str, Any]) -> str:
         """

{skillware-0.2.4 → skillware-0.2.6}/skillware.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.2.4
+Version: 0.2.6
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logic Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -38,6 +38,7 @@ Requires-Dist: pyyaml
 Requires-Dist: anthropic
 Requires-Dist: google-generativeai
 Requires-Dist: pymupdf
+Requires-Dist: beautifulsoup4
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
@@ -102,7 +103,8 @@ Skillware/
 │       └── skill_name/         # The Skill bundle
 │           ├── manifest.yaml   # Definition, schema, and constitution
 │           ├── skill.py        # Executable Python logic
-│           └── instructions.md # Cognitive map for the LLM
+│           ├── instructions.md # Cognitive map for the LLM
+│           └── test_skill.py   # Unit tests & schema validation
 ├── skillware/                  # Core Framework Package
 │   └── core/
 │       ├── base_skill.py       # Abstract Base Class for skills
@@ -172,20 +174,26 @@ print(response.text)
 ## Documentation
 
 *   **[Core Logic & Philosophy](docs/introduction.md)**: Details on how Skillware decouples Logic, Cognition, and Governance.
+*   **[Testing Guidelines](docs/TESTING.md)**: Instructions for validating skills and checking local coverage.
+*   **[Usage guides](docs/usage/README.md)**: Provider adapters and navigation to integration docs.
+*   **[Agent loops](docs/usage/agent_loops.md)**: Shared load, tool-call, and `execute` pattern across providers.
 *   **[Usage Guide: Gemini](docs/usage/gemini.md)**: Integration with Google's GenAI SDK.
 *   **[Usage Guide: Claude](docs/usage/claude.md)**: Integration with Anthropic's SDK.
+*   **[Usage Guide: OpenAI](docs/usage/openai.md)**: Integration with OpenAI Chat Completions tool calling.
+*   **[Usage Guide: DeepSeek](docs/usage/deepseek.md)**: Integration with the DeepSeek API via `to_deepseek_tool()`.
 *   **[Usage Guide: Ollama](docs/usage/ollama.md)**: Native integration for local models via Ollama.
+*   **[API Keys for Skills](docs/usage/api_keys.md)**: Environment variables, cloud/CI setup, and security for skills that call external APIs.
 *   **[Skill Library](docs/skills/README.md)**: Available capabilities.
 
 ## Contributing
 
-We are building the "App Store" for Agents and require professional, robust, and safe skills.
+We are building the "App Store" for Agents and require professional, robust, and safe skills. We welcome contributions to the skill registry, documentation, tests, and core framework.
 
-We actively encourage both humans and autonomous agents to contribute to this repository!
-
-* Please read our **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** which outlines our strict expectations for deterministic outputs, zero LLM code generation, and safety boundaries.
-* When submitting skills, our new **Agent-Friendly Pull Request Template** provides a checklist to ensure your logic aligns natively with `loader.py` and `base_skill.py`.
-* Please also review **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed guidelines on folder structure and schema definitions.
+* **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution types, skill standard, pull request process, and navigation to all contributor docs.
+* **[Agent Contribution Workflow](docs/contributing/ai_native_workflow.md)** — Workflow for AI agents contributing to the repository (operators supervise).
+* **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** — Deterministic outputs, safety boundaries, and acceptable use of skills.
+* **[TESTING.md](docs/TESTING.md)** — Local linting and pytest before you open a PR.
+* **[Pull request template](.github/PULL_REQUEST_TEMPLATE.md)** — Checklists for skills, docs, and framework changes (complete only the sections that apply).
 
 ## Comparison
 

{skillware-0.2.4 → skillware-0.2.6}/skillware.egg-info/SOURCES.txt

@@ -5,6 +5,9 @@ skills/compliance/mica_module/__init__.py
 skills/compliance/mica_module/skill.py
 skills/compliance/pii_masker/__init__.py
 skills/compliance/pii_masker/skill.py
+skills/compliance/tos_evaluator/__init__.py
+skills/compliance/tos_evaluator/skill.py
+skills/compliance/tos_evaluator/test_skill.py
 skills/data_engineering/synthetic_generator/__init__.py
 skills/data_engineering/synthetic_generator/skill.py
 skills/finance/wallet_screening/__init__.py
@@ -26,4 +29,5 @@ skillware/core/base_skill.py
 skillware/core/env.py
 skillware/core/loader.py
 tests/test_loader.py
-tests/test_mica_module.py
+tests/test_mica_module.py
+tests/test_skill_issuer.py

{skillware-0.2.4 → skillware-0.2.6}/skillware.egg-info/requires.txt

@@ -3,6 +3,7 @@ pyyaml
 anthropic
 google-generativeai
 pymupdf
+beautifulsoup4
 
 [dev]
 pytest

skillware-0.2.6/tests/test_loader.py

@@ -0,0 +1,122 @@
+import pytest
+from skillware.core.loader import SkillLoader
+
+
+def test_load_skill_not_found():
+    with pytest.raises(FileNotFoundError):
+        SkillLoader.load_skill("nonexistent_skill_path_12345")
+
+
+def test_to_ollama_prompt():
+    dummy_bundle = {
+        "manifest": {
+            "name": "test_ollama_skill",
+            "description": "A very useful test skill.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "arg1": {"type": "string", "description": "The first arg"}
+                },
+                "required": ["arg1"]
+            }
+        }
+    }
+
+    prompt = SkillLoader.to_ollama_prompt(dummy_bundle)
+    assert "### Tool: `test_ollama_skill`" in prompt
+    assert "**Description:** A very useful test skill." in prompt
+    assert "- `arg1` (string): The first arg [Required]" in prompt
+
+
+def test_to_gemini_tool():
+    dummy_bundle = {
+        "manifest": {
+            "name": "test_gemini_skill",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "param1": {"type": "string"}
+                }
+            }
+        }
+    }
+    tool = SkillLoader.to_gemini_tool(dummy_bundle)
+    assert tool["name"] == "test_gemini_skill"
+    # Gemini requires UPPERCASE types for Protobufs
+    assert tool["parameters"]["type"] == "OBJECT"
+    assert tool["parameters"]["properties"]["param1"]["type"] == "STRING"
+
+
+def test_to_claude_tool():
+    dummy_bundle = {
+        "manifest": {
+            "name": "test_claude_skill",
+            "description": "desc",
+            "parameters": {
+                "type": "object",
+                "properties": {"arg_claude": {"type": "string"}}
+            }
+        }
+    }
+    tool = SkillLoader.to_claude_tool(dummy_bundle)
+    assert tool["name"] == "test_claude_skill"
+    assert tool["input_schema"]["type"] == "object"
+
+
+def test_sanitize_openai_tool_name():
+    assert (
+        SkillLoader._sanitize_openai_tool_name("compliance/tos_evaluator")
+        == "compliance_tos_evaluator"
+    )
+    assert SkillLoader._sanitize_openai_tool_name("wallet_screening") == "wallet_screening"
+    assert SkillLoader._sanitize_openai_tool_name("") == "unknown_tool"
+    assert SkillLoader._sanitize_openai_tool_name("a" * 80).startswith("a")
+    assert len(SkillLoader._sanitize_openai_tool_name("a" * 80)) == 64
+
+
+def test_to_openai_tool():
+    dummy_bundle = {
+        "manifest": {
+            "name": "compliance/tos_evaluator",
+            "description": "Evaluate site policy.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target_url": {"type": "string", "description": "URL"}
+                },
+                "required": ["target_url"],
+            },
+        }
+    }
+    tool = SkillLoader.to_openai_tool(dummy_bundle)
+    assert tool["type"] == "function"
+    assert tool["function"]["name"] == "compliance_tos_evaluator"
+    assert tool["function"]["description"] == "Evaluate site policy."
+    assert tool["function"]["parameters"]["type"] == "object"
+    assert "target_url" in tool["function"]["parameters"]["properties"]
+
+
+def test_sanitize_deepseek_tool_name():
+    assert (
+        SkillLoader._sanitize_deepseek_tool_name("compliance/tos_evaluator")
+        == "compliance_tos_evaluator"
+    )
+
+
+def test_to_deepseek_tool():
+    dummy_bundle = {
+        "manifest": {
+            "name": "compliance/tos_evaluator",
+            "description": "Evaluate site policy.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target_url": {"type": "string", "description": "URL"}
+                },
+                "required": ["target_url"],
+            },
+        }
+    }
+    tool = SkillLoader.to_deepseek_tool(dummy_bundle)
+    assert tool["type"] == "function"
+    assert tool["function"]["name"] == "compliance_tos_evaluator"

skillware-0.2.6/tests/test_skill_issuer.py

@@ -0,0 +1,89 @@
+"""Registry skills must declare issuer attribution (name + email required)."""
+
+import json
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_ROOT = REPO_ROOT / "skills"
+
+PLACEHOLDER_NAMES = frozenset({"your name"})
+PLACEHOLDER_EMAILS = frozenset({"you@example.com"})
+PLACEHOLDER_GITHUB = frozenset({"your_github_username"})
+PLACEHOLDER_ORGS = frozenset({"your org"})
+
+
+def _discover_skill_dirs():
+    if not SKILLS_ROOT.is_dir():
+        return []
+    return sorted(p.parent for p in SKILLS_ROOT.rglob("manifest.yaml"))
+
+
+def _load_manifest(skill_dir: Path) -> dict:
+    with open(skill_dir / "manifest.yaml", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    return data if isinstance(data, dict) else {}
+
+
+def _assert_real_issuer(issuer: dict, context: str) -> None:
+    assert isinstance(issuer, dict), f"{context}: issuer must be a mapping"
+
+    name = (issuer.get("name") or "").strip()
+    email = (issuer.get("email") or "").strip()
+    assert name, f"{context}: issuer.name is required"
+    assert email, f"{context}: issuer.email is required"
+
+    assert name.lower() not in PLACEHOLDER_NAMES, (
+        f"{context}: issuer.name must not be a template placeholder"
+    )
+    assert email.lower() not in PLACEHOLDER_EMAILS, (
+        f"{context}: issuer.email must not be a template placeholder"
+    )
+
+    github = (issuer.get("github") or "").strip()
+    if github:
+        assert github.lower() not in PLACEHOLDER_GITHUB, (
+            f"{context}: issuer.github must not be a template placeholder"
+        )
+
+    org = (issuer.get("org") or "").strip()
+    if org:
+        assert org.lower() not in PLACEHOLDER_ORGS, (
+            f"{context}: issuer.org must not be a template placeholder"
+        )
+
+
+def test_registry_skills_declare_issuer():
+    skill_dirs = _discover_skill_dirs()
+    assert skill_dirs, "expected at least one skill under skills/"
+
+    for skill_dir in skill_dirs:
+        rel = skill_dir.relative_to(REPO_ROOT).as_posix()
+        manifest = _load_manifest(skill_dir)
+        _assert_real_issuer(manifest.get("issuer"), f"{rel} manifest.yaml")
+
+
+def test_registry_card_issuer_matches_manifest_when_present():
+    for skill_dir in _discover_skill_dirs():
+        rel = skill_dir.relative_to(REPO_ROOT).as_posix()
+        manifest_issuer = _load_manifest(skill_dir).get("issuer")
+        _assert_real_issuer(manifest_issuer, f"{rel} manifest.yaml")
+
+        card_path = skill_dir / "card.json"
+        if not card_path.is_file():
+            continue
+
+        with open(card_path, encoding="utf-8") as f:
+            card = json.load(f)
+
+        card_issuer = card.get("issuer")
+        assert card_issuer is not None, f"{rel} card.json should include issuer"
+        _assert_real_issuer(card_issuer, f"{rel} card.json")
+
+        assert (card_issuer.get("name") or "").strip() == (
+            manifest_issuer.get("name") or ""
+        ).strip(), f"{rel}: card issuer.name should match manifest"
+        assert (card_issuer.get("email") or "").strip() == (
+            manifest_issuer.get("email") or ""
+        ).strip(), f"{rel}: card issuer.email should match manifest"

skillware-0.2.4/tests/test_loader.py

@@ -1,63 +0,0 @@
-import pytest
-from skillware.core.loader import SkillLoader
-
-
-def test_load_skill_not_found():
-    with pytest.raises(FileNotFoundError):
-        SkillLoader.load_skill("nonexistent_skill_path_12345")
-
-
-def test_to_ollama_prompt():
-    dummy_bundle = {
-        "manifest": {
-            "name": "test_ollama_skill",
-            "description": "A very useful test skill.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "arg1": {"type": "string", "description": "The first arg"}
-                },
-                "required": ["arg1"]
-            }
-        }
-    }
-
-    prompt = SkillLoader.to_ollama_prompt(dummy_bundle)
-    assert "### Tool: `test_ollama_skill`" in prompt
-    assert "**Description:** A very useful test skill." in prompt
-    assert "- `arg1` (string): The first arg [Required]" in prompt
-
-
-def test_to_gemini_tool():
-    dummy_bundle = {
-        "manifest": {
-            "name": "test_gemini_skill",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "param1": {"type": "string"}
-                }
-            }
-        }
-    }
-    tool = SkillLoader.to_gemini_tool(dummy_bundle)
-    assert tool["name"] == "test_gemini_skill"
-    # Gemini requires UPPERCASE types for Protobufs
-    assert tool["parameters"]["type"] == "OBJECT"
-    assert tool["parameters"]["properties"]["param1"]["type"] == "STRING"
-
-
-def test_to_claude_tool():
-    dummy_bundle = {
-        "manifest": {
-            "name": "test_claude_skill",
-            "description": "desc",
-            "parameters": {
-                "type": "object",
-                "properties": {"arg_claude": {"type": "string"}}
-            }
-        }
-    }
-    tool = SkillLoader.to_claude_tool(dummy_bundle)
-    assert tool["name"] == "test_claude_skill"
-    assert tool["input_schema"]["type"] == "object"