weavert-kit-chat 0.1.0__tar.gz

weavert_kit_chat-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: weavert-kit-chat
+Version: 0.1.0
+Summary: Chat-oriented product kit for extracted WeaveRT scenario packs.
+Author: WeaveRT Maintainers
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/xyz2b/weave-ai-runtime
+Project-URL: Documentation, https://github.com/xyz2b/weave-ai-runtime/tree/main/docs
+Project-URL: Repository, https://github.com/xyz2b/weave-ai-runtime
+Project-URL: Issues, https://github.com/xyz2b/weave-ai-runtime/issues
+Keywords: weavert,agents,ai,product-kit,scenario-pack
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: weavert<0.2.0,>=0.1.0
+Requires-Dist: weavert-kit-common-retrieval<0.2.0,>=0.1.0
+Requires-Dist: weavert-kit-common-web<0.2.0,>=0.1.0
+
+# Chat Product Kit
+
+Canonical import root: `weavert_kit_chat`
+
+## What this package owns
+
+- the `weavert-scenario-chat` scenario pack
+- chat-oriented product-profile defaults layered on shared grounding packages
+
+## Canonical names
+
+- install name: `weavert-kit-chat`
+- import root: `weavert_kit_chat`
+- runtime activation: `weavert-scenario-chat`
+
+The public install name stays separate from the runtime scenario-pack activation name.
+
+## Shared packages it composes
+
+- `weavert_kit_common_retrieval`
+- `weavert_kit_common_web`
+
+## See also
+
+- `../README.md`
+- `../common/README.md`
+- `../../../docs/guides/use-scenario-packs.md`
+- `../../../docs/introduction/use-cases.md`

weavert_kit_chat-0.1.0/README.md

@@ -0,0 +1,28 @@
+# Chat Product Kit
+
+Canonical import root: `weavert_kit_chat`
+
+## What this package owns
+
+- the `weavert-scenario-chat` scenario pack
+- chat-oriented product-profile defaults layered on shared grounding packages
+
+## Canonical names
+
+- install name: `weavert-kit-chat`
+- import root: `weavert_kit_chat`
+- runtime activation: `weavert-scenario-chat`
+
+The public install name stays separate from the runtime scenario-pack activation name.
+
+## Shared packages it composes
+
+- `weavert_kit_common_retrieval`
+- `weavert_kit_common_web`
+
+## See also
+
+- `../README.md`
+- `../common/README.md`
+- `../../../docs/guides/use-scenario-packs.md`
+- `../../../docs/introduction/use-cases.md`

weavert_kit_chat-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "weavert-kit-chat"
+version = "0.1.0"
+description = "Chat-oriented product kit for extracted WeaveRT scenario packs."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "WeaveRT Maintainers" }]
+requires-python = ">=3.11"
+dependencies = [
+  "weavert>=0.1.0,<0.2.0",
+  "weavert-kit-common-retrieval>=0.1.0,<0.2.0",
+  "weavert-kit-common-web>=0.1.0,<0.2.0",
+]
+keywords = ["weavert", "agents", "ai", "product-kit", "scenario-pack"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/xyz2b/weave-ai-runtime"
+Documentation = "https://github.com/xyz2b/weave-ai-runtime/tree/main/docs"
+Repository = "https://github.com/xyz2b/weave-ai-runtime"
+Issues = "https://github.com/xyz2b/weave-ai-runtime/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

weavert_kit_chat-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

weavert_kit_chat-0.1.0/src/weavert_kit_chat/__init__.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from weavert.package_system.protocols import RuntimePackageManifest
+from weavert.extension_contracts.scenario_runtime_packs import (
+    ReferenceScenarioPackShape,
+    build_reference_scenario_pack_manifest,
+)
+from weavert_kit_common_retrieval import CHAT_RETRIEVAL_TOOLS, reference_shared_package_manifest as retrieval_package_manifest
+from weavert_kit_common_web import CHAT_WEB_TOOLS, reference_shared_package_manifest as web_package_manifest
+
+from ._builtins import (
+    CHAT_SCENARIO_AGENTS,
+    CHAT_SCENARIO_SKILLS,
+    chat_scenario_builtin_agents,
+    chat_scenario_builtin_skills,
+)
+
+CHAT_WORKFLOW_CONTROL_TOOLS = ("ask_user",)
+
+REFERENCE_SCENARIO_PACK_SHAPE = ReferenceScenarioPackShape(
+    package_name="weavert-scenario-chat",
+    profile="chat",
+    display_name="AI chat",
+    description="Reference scenario pack for read-mostly chat experiences.",
+    recommended_distribution="weavert-core",
+    recommended_first_party_packages=("weavert-memory",),
+    shared_package_dependencies=(
+        "weavert-shared-retrieval",
+        "weavert-bridge-web",
+    ),
+    expected_tools=(*CHAT_RETRIEVAL_TOOLS, *CHAT_WEB_TOOLS, *CHAT_WORKFLOW_CONTROL_TOOLS),
+    expected_agents=CHAT_SCENARIO_AGENTS,
+    expected_skills=("remember", *CHAT_SCENARIO_SKILLS),
+    default_boundaries=(
+        "read-mostly by default",
+        "no implicit workspace mutation or shell execution surfaces",
+        "retrieval and web grounding stay shared-package concerns while workflow roles stay scenario-pack owned",
+    ),
+    app_owned_wiring=(
+        "model provider selection",
+        "session/transcript store selection",
+        "host binding for web, mobile, or support surfaces",
+        "final permission policy composition",
+    ),
+    host_assumptions=(
+        "host remains lightweight and may only expose notifications or approval prompts",
+    ),
+    permission_policy_posture=(
+        "default to read-only or approval-first policies",
+        "treat any write-capable bridge as an app-owned escalation decision",
+    ),
+    profile_prompt_fragments=(
+        "Scenario profile: AI chat.",
+        "Preserve read-mostly defaults and avoid implicit workspace mutation or shell execution.",
+    ),
+    workflow_agent_ids=CHAT_SCENARIO_AGENTS,
+    workflow_skill_ids=CHAT_SCENARIO_SKILLS,
+    notes=(
+        "Chat inherits memory and retrieval posture without inheriting coding defaults.",
+        "The chat scenario pack owns workflow agents and skills, while shared retrieval/web packages own the grounding tools.",
+    ),
+)
+
+
+def reference_scenario_pack_shapes() -> tuple[ReferenceScenarioPackShape, ...]:
+    return (REFERENCE_SCENARIO_PACK_SHAPE,)
+
+
+def reference_scenario_pack_shape(name: str | None = None) -> ReferenceScenarioPackShape:
+    normalized = REFERENCE_SCENARIO_PACK_SHAPE.package_name if name is None else str(name)
+    if normalized in {
+        REFERENCE_SCENARIO_PACK_SHAPE.package_name,
+        REFERENCE_SCENARIO_PACK_SHAPE.profile,
+        REFERENCE_SCENARIO_PACK_SHAPE.display_name,
+    }:
+        return REFERENCE_SCENARIO_PACK_SHAPE
+    raise KeyError(f"Unknown chat scenario pack shape: {name}")
+
+
+def reference_scenario_pack_manifest() -> RuntimePackageManifest:
+    return build_reference_scenario_pack_manifest(
+        REFERENCE_SCENARIO_PACK_SHAPE,
+        builtin_agents=chat_scenario_builtin_agents,
+        builtin_skills=chat_scenario_builtin_skills,
+    )
+
+
+def reference_scenario_pack_manifests() -> tuple[RuntimePackageManifest, ...]:
+    return (reference_scenario_pack_manifest(),)
+
+
+def chat_scenario_runtime_pack_manifests() -> tuple[RuntimePackageManifest, ...]:
+    return (
+        retrieval_package_manifest(),
+        web_package_manifest(),
+        reference_scenario_pack_manifest(),
+    )
+
+
+__all__ = [
+    "CHAT_SCENARIO_AGENTS",
+    "CHAT_SCENARIO_SKILLS",
+    "CHAT_WORKFLOW_CONTROL_TOOLS",
+    "REFERENCE_SCENARIO_PACK_SHAPE",
+    "chat_scenario_runtime_pack_manifests",
+    "reference_scenario_pack_manifest",
+    "reference_scenario_pack_manifests",
+    "reference_scenario_pack_shape",
+    "reference_scenario_pack_shapes",
+]

weavert_kit_chat-0.1.0/src/weavert_kit_chat/_builtins.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+from weavert.builtins.definition_helpers import static_semantics
+from weavert.definitions import (
+    AgentDefinition,
+    DefinitionOrigin,
+    DefinitionSource,
+    MemoryScope,
+    PermissionMode,
+    SkillDefinition,
+    SkillExecutionContext,
+    ToolClassifierInput,
+    ToolDefinition,
+    ToolPresentationEmphasis,
+    ToolRiskLevel,
+    ToolTraits,
+    ToolUsePresentation,
+)
+from ._tool_impls import (
+    grounding_web_fetch_tool,
+    grounding_web_search_tool,
+    prepare_citations_tool,
+    retrieve_context_tool,
+    validate_grounding_web_fetch,
+    validate_grounding_web_search,
+    validate_prepare_citations_tool,
+    validate_retrieve_context_tool,
+)
+
+CHAT_RETRIEVAL_TOOLS = (
+    "retrieve_context",
+    "prepare_citations",
+)
+CHAT_WEB_TOOLS = (
+    "grounding_web_search",
+    "grounding_web_fetch",
+)
+CHAT_SCENARIO_AGENTS = (
+    "researcher",
+    "support-agent",
+    "memory-curator",
+)
+CHAT_SCENARIO_SKILLS = (
+    "chat-summarize",
+    "answer-with-citations",
+    "clarify-request",
+    "capture-preferences",
+)
+
+
+def chat_shared_retrieval_builtin_tools() -> tuple[ToolDefinition, ...]:
+    origin = DefinitionOrigin(DefinitionSource.BUNDLED)
+    item_schema = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "string"},
+            "title": {"type": "string"},
+            "content": {"type": "string"},
+            "excerpt": {"type": "string"},
+            "url": {"type": "string"},
+            "source_kind": {"type": "string"},
+            "metadata": {"type": "object"},
+        },
+        "additionalProperties": True,
+    }
+    return (
+        ToolDefinition(
+            name="retrieve_context",
+            description="Rank grounding notes, passages, and optional runtime memory for a chat query.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "items": {"type": "array", "items": item_schema},
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 12},
+                    "include_memory": {"type": "boolean"},
+                    "memory_scope": {
+                        "type": "string",
+                        "enum": [MemoryScope.USER.value, MemoryScope.PROJECT.value, MemoryScope.LOCAL.value],
+                    },
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+            traits=ToolTraits(read_only=True, concurrency_safe=True),
+            semantics=_read_only_tool_semantics(
+                title="Retrieve grounding context",
+                operation="retrieve_context",
+                summary_prefix="Retrieve grounding context",
+                subtitle_key="query",
+                risk_level=ToolRiskLevel.READ,
+                tags=("grounding", "retrieval"),
+            ),
+            validate_input=validate_retrieve_context_tool,
+            execute=retrieve_context_tool,
+            origin=origin,
+        ),
+        ToolDefinition(
+            name="prepare_citations",
+            description="Turn retrieved grounding items into a flat citation bundle for chat answers.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "items": {"type": "array", "items": item_schema},
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 12},
+                },
+                "required": ["items"],
+                "additionalProperties": False,
+            },
+            traits=ToolTraits(read_only=True, concurrency_safe=True),
+            semantics=_read_only_tool_semantics(
+                title="Prepare citations",
+                operation="prepare_citations",
+                summary_prefix="Prepare citations",
+                subtitle_key="limit",
+                risk_level=ToolRiskLevel.READ,
+                tags=("grounding", "citations"),
+            ),
+            validate_input=validate_prepare_citations_tool,
+            execute=prepare_citations_tool,
+            origin=origin,
+        ),
+    )
+
+
+def chat_web_grounding_builtin_tools() -> tuple[ToolDefinition, ...]:
+    origin = DefinitionOrigin(DefinitionSource.BUNDLED)
+    return (
+        ToolDefinition(
+            name="grounding_web_search",
+            description="Search the web for chat-safe grounding candidates.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 8},
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+            traits=ToolTraits(read_only=True, concurrency_safe=True),
+            semantics=_network_tool_semantics(
+                title="Search grounding sources",
+                operation="grounding_web_search",
+                summary_prefix="Search grounding sources",
+                subtitle_key="query",
+                tags=("grounding", "web", "search"),
+            ),
+            validate_input=validate_grounding_web_search,
+            execute=grounding_web_search_tool,
+            origin=origin,
+        ),
+        ToolDefinition(
+            name="grounding_web_fetch",
+            description="Fetch a remote page and return chat-safe text for grounding.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "url": {"type": "string"},
+                    "timeout_ms": {"type": "integer", "minimum": 1},
+                    "max_chars": {"type": "integer", "minimum": 500, "maximum": 32000},
+                },
+                "required": ["url"],
+                "additionalProperties": False,
+            },
+            traits=ToolTraits(read_only=True, concurrency_safe=True),
+            semantics=_network_tool_semantics(
+                title="Fetch grounding page",
+                operation="grounding_web_fetch",
+                summary_prefix="Fetch grounding page",
+                subtitle_key="url",
+                tags=("grounding", "web", "fetch"),
+            ),
+            validate_input=validate_grounding_web_fetch,
+            execute=grounding_web_fetch_tool,
+            origin=origin,
+        ),
+    )
+
+
+def chat_scenario_builtin_agents() -> tuple[AgentDefinition, ...]:
+    origin = DefinitionOrigin(DefinitionSource.BUNDLED)
+    return (
+        AgentDefinition(
+            name="researcher",
+            description="Gather read-only evidence bundles for grounded chat answers.",
+            prompt=(
+                "You are the grounded-chat researcher.\n\n"
+                "Workflow contract:\n"
+                "1. Start with read-only grounding surfaces.\n"
+                "2. Use `grounding_web_search` and `grounding_web_fetch` for fresh external facts when needed.\n"
+                "3. Use `retrieve_context` to rank notes, memory, or fetched passages before summarizing.\n"
+                "4. Use `prepare_citations` before handing off a final evidence bundle.\n"
+                "5. Never imply shell access, workspace mutation, or uninspected sources."
+            ),
+            tools=(*CHAT_RETRIEVAL_TOOLS, *CHAT_WEB_TOOLS, "ask_user"),
+            skills=("chat-summarize", "answer-with-citations", "clarify-request"),
+            permission_mode=PermissionMode.DEFAULT,
+            max_turns=6,
+            memory=MemoryScope.PROJECT,
+            origin=origin,
+        ),
+        AgentDefinition(
+            name="support-agent",
+            description="Answer user support questions with clarification and citations.",
+            prompt=(
+                "You are the grounded-chat support agent.\n\n"
+                "Workflow contract:\n"
+                "1. Clarify the user's goal when the policy, product, or account scope is ambiguous.\n"
+                "2. Prefer cited, read-only answers over unsupported guesses.\n"
+                "3. Use retrieval and web grounding surfaces before finalizing an answer.\n"
+                "4. Capture durable user preferences only when they are explicit and stable.\n"
+                "5. Do not request workspace or shell mutation as part of the default support flow."
+            ),
+            tools=(*CHAT_RETRIEVAL_TOOLS, *CHAT_WEB_TOOLS, "ask_user"),
+            skills=(
+                "chat-summarize",
+                "answer-with-citations",
+                "clarify-request",
+                "capture-preferences",
+                "remember",
+            ),
+            permission_mode=PermissionMode.DEFAULT,
+            max_turns=6,
+            memory=MemoryScope.PROJECT,
+            origin=origin,
+        ),
+        AgentDefinition(
+            name="memory-curator",
+            description="Curate durable chat preferences and reusable support facts.",
+            prompt=(
+                "You are the grounded-chat memory curator.\n\n"
+                "Workflow contract:\n"
+                "1. Inspect recent context and retrieved notes before recording anything durable.\n"
+                "2. Prefer stable preferences, conventions, and reusable support facts.\n"
+                "3. Use `remember` only when the information is explicit, durable, and helpful later.\n"
+                "4. Keep the posture read-mostly and never ask for coding-oriented mutation surfaces."
+            ),
+            tools=(*CHAT_RETRIEVAL_TOOLS, "ask_user"),
+            skills=("capture-preferences", "remember", "chat-summarize"),
+            permission_mode=PermissionMode.DEFAULT,
+            max_turns=4,
+            memory=MemoryScope.PROJECT,
+            origin=origin,
+        ),
+    )
+
+
+def chat_scenario_builtin_skills() -> tuple[SkillDefinition, ...]:
+    origin = DefinitionOrigin(DefinitionSource.BUNDLED)
+    return (
+        SkillDefinition(
+            name="chat-summarize",
+            description="Summarize retrieved grounding without dropping important caveats.",
+            content=(
+                "Summarize the material already in hand.\n\n"
+                "1. Start from retrieved notes, fetched passages, or durable memory.\n"
+                "2. Separate confirmed facts from uncertainty.\n"
+                "3. Keep the summary concise, user-facing, and faithful to the sources."
+            ),
+            execution_context=SkillExecutionContext.INLINE,
+            origin=origin,
+        ),
+        SkillDefinition(
+            name="answer-with-citations",
+            description="Assemble a grounded answer that cites supporting evidence explicitly.",
+            content=(
+                "Answer with visible grounding.\n\n"
+                "1. Retrieve or fetch the best evidence first.\n"
+                "2. Call `prepare_citations` on the supporting items before drafting the answer.\n"
+                "3. Cite only evidence you actually inspected.\n"
+                "4. State uncertainty when the grounding is thin or incomplete."
+            ),
+            execution_context=SkillExecutionContext.INLINE,
+            origin=origin,
+        ),
+        SkillDefinition(
+            name="clarify-request",
+            description="Ask a short clarification before grounding an ambiguous request.",
+            content=(
+                "When the request is ambiguous or missing the policy/product scope:\n\n"
+                "1. Ask the shortest question that unblocks a grounded answer.\n"
+                "2. Prefer one focused clarification over a long questionnaire.\n"
+                "3. Resume grounding once the missing detail is provided."
+            ),
+            execution_context=SkillExecutionContext.INLINE,
+            origin=origin,
+        ),
+        SkillDefinition(
+            name="capture-preferences",
+            description="Record durable user preferences and recurring support facts.",
+            content=(
+                "Capture only stable preferences or reusable support facts.\n\n"
+                "1. Confirm the preference or fact is explicit and durable.\n"
+                "2. Use `remember` when the information should survive future turns.\n"
+                "3. Skip volatile or one-off details."
+            ),
+            execution_context=SkillExecutionContext.INLINE,
+            origin=origin,
+        ),
+    )
+
+
+def _read_only_tool_semantics(
+    *,
+    title: str,
+    operation: str,
+    summary_prefix: str,
+    subtitle_key: str,
+    risk_level: ToolRiskLevel,
+    tags: tuple[str, ...],
+):
+    return static_semantics(
+        read_only=True,
+        concurrency_safe=True,
+        tool_use_presentation=lambda tool_input, _context: ToolUsePresentation(
+            title=title,
+            subtitle=str(tool_input.get(subtitle_key) or "grounding"),
+            emphasis=ToolPresentationEmphasis.LOW,
+        ),
+        classifier_input=lambda tool_input, _context: ToolClassifierInput(
+            operation=operation,
+            summary=f"{summary_prefix}: {tool_input.get(subtitle_key) or 'grounding'}",
+            risk_level=risk_level,
+            side_effects=False,
+            tags=tags,
+        ),
+    )
+
+
+def _network_tool_semantics(
+    *,
+    title: str,
+    operation: str,
+    summary_prefix: str,
+    subtitle_key: str,
+    tags: tuple[str, ...],
+):
+    return static_semantics(
+        read_only=True,
+        concurrency_safe=True,
+        tool_use_presentation=lambda tool_input, _context: ToolUsePresentation(
+            title=title,
+            subtitle=str(tool_input.get(subtitle_key) or "grounding"),
+            emphasis=ToolPresentationEmphasis.LOW,
+        ),
+        classifier_input=lambda tool_input, _context: ToolClassifierInput(
+            operation=operation,
+            summary=f"{summary_prefix}: {tool_input.get(subtitle_key) or 'grounding'}",
+            target_urls=(
+                (str(tool_input[subtitle_key]),)
+                if subtitle_key == "url" and tool_input.get(subtitle_key) is not None
+                else ()
+            ),
+            risk_level=ToolRiskLevel.NETWORK,
+            side_effects=False,
+            tags=tags,
+        ),
+    )
+
+
+__all__ = [
+    "CHAT_RETRIEVAL_TOOLS",
+    "CHAT_SCENARIO_AGENTS",
+    "CHAT_SCENARIO_SKILLS",
+    "CHAT_WEB_TOOLS",
+    "chat_scenario_builtin_agents",
+    "chat_scenario_builtin_skills",
+    "chat_shared_retrieval_builtin_tools",
+    "chat_web_grounding_builtin_tools",
+]

weavert_kit_chat-0.1.0/src/weavert_kit_chat/_tool_impls.py

@@ -0,0 +1,539 @@
+from __future__ import annotations
+
+import asyncio
+import html
+import ipaddress
+import re
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from weavert.definitions import MemoryScope, ValidationOutcome
+from weavert.tool_runtime import ToolContext
+
+_STOPWORDS = {
+    "about",
+    "after",
+    "again",
+    "also",
+    "been",
+    "from",
+    "have",
+    "into",
+    "just",
+    "more",
+    "that",
+    "their",
+    "them",
+    "then",
+    "they",
+    "this",
+    "what",
+    "when",
+    "where",
+    "which",
+    "with",
+    "would",
+}
+_HTML_TITLE_RE = re.compile(r"<title[^>]*>(?P<title>.*?)</title>", re.IGNORECASE | re.DOTALL)
+_HTML_SCRIPT_STYLE_RE = re.compile(
+    r"<(script|style)[^>]*>.*?</\1>",
+    re.IGNORECASE | re.DOTALL,
+)
+_HTML_TAG_RE = re.compile(r"<[^>]+>")
+_WHITESPACE_RE = re.compile(r"\s+")
+_MAX_FETCH_BYTES = 256_000
+_DEFAULT_FETCH_CHARS = 12_000
+_GROUNDING_SEARCH_BASE_URL = "https://duckduckgo.com/html/"
+_GROUNDING_REDIRECT_HOSTS = frozenset({"duckduckgo.com", "www.duckduckgo.com"})
+_GROUNDING_BLOCKED_HOSTS = frozenset(
+    {
+        "localhost",
+        "localhost.localdomain",
+        "metadata.google.internal",
+    }
+)
+_GROUNDING_BLOCKED_HOST_SUFFIXES = (
+    ".localhost",
+    ".localdomain",
+    ".local",
+    ".internal",
+    ".home.arpa",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _GroundingCandidate:
+    candidate_id: str
+    title: str
+    content: str
+    url: str | None
+    source_kind: str
+    metadata: dict[str, Any]
+
+
+def validate_retrieve_context_tool(tool_input: dict[str, Any], _: ToolContext) -> ValidationOutcome:
+    query = str(tool_input.get("query") or "").strip()
+    if not query:
+        return ValidationOutcome(False, "query must be non-empty")
+    items = tool_input.get("items")
+    if items is not None and not isinstance(items, list):
+        return ValidationOutcome(False, "items must be an array when provided")
+    include_memory = tool_input.get("include_memory", True)
+    if not include_memory and not items:
+        return ValidationOutcome(False, "items are required when include_memory is false")
+    memory_scope = str(tool_input.get("memory_scope") or "").strip()
+    if memory_scope and memory_scope not in {scope.value for scope in MemoryScope}:
+        return ValidationOutcome(False, f"Unsupported memory_scope: {memory_scope}")
+    return ValidationOutcome(True)
+
+
+async def retrieve_context_tool(tool_input: dict[str, Any], context: ToolContext) -> dict[str, Any]:
+    query = str(tool_input["query"]).strip()
+    limit = max(1, min(int(tool_input.get("limit", 5)), 12))
+    include_memory = tool_input.get("include_memory", True)
+    candidates = list(_inline_candidates(tool_input.get("items")))
+    if include_memory:
+        candidates.extend(_memory_candidates(context, tool_input.get("memory_scope")))
+
+    query_tokens = _tokenize(query)
+    if not candidates:
+        return {"query": query, "results": [], "sources": {"external": 0, "memory": 0}}
+
+    scored: list[dict[str, Any]] = []
+    for candidate in candidates:
+        score = _candidate_score(query_tokens, candidate)
+        if score <= 0:
+            continue
+        excerpt = _best_excerpt(query_tokens, candidate.content)
+        scored.append(
+            {
+                "id": candidate.candidate_id,
+                "title": candidate.title,
+                "excerpt": excerpt,
+                "content": _truncate_text(candidate.content, 600),
+                "score": round(score, 3),
+                "url": candidate.url,
+                "source_kind": candidate.source_kind,
+                "metadata": dict(candidate.metadata),
+            }
+        )
+    scored.sort(key=lambda item: (-float(item["score"]), str(item["title"]).lower(), str(item["id"])))
+    results = scored[:limit]
+    return {
+        "query": query,
+        "results": results,
+        "sources": {
+            "external": sum(1 for item in results if item["source_kind"] == "external"),
+            "memory": sum(1 for item in results if item["source_kind"] == "memory"),
+        },
+    }
+
+
+def validate_prepare_citations_tool(tool_input: dict[str, Any], _: ToolContext) -> ValidationOutcome:
+    items = tool_input.get("items")
+    if not isinstance(items, list) or not items:
+        return ValidationOutcome(False, "items must contain at least one citation candidate")
+    return ValidationOutcome(True)
+
+
+async def prepare_citations_tool(tool_input: dict[str, Any], _: ToolContext) -> dict[str, Any]:
+    limit = max(1, min(int(tool_input.get("limit", 5)), 12))
+    citations: list[dict[str, Any]] = []
+    seen: set[tuple[str, str, str]] = set()
+    for raw in tool_input.get("items") or ():
+        if not isinstance(raw, Mapping):
+            continue
+        title = str(raw.get("title") or raw.get("id") or "Untitled source").strip() or "Untitled source"
+        excerpt = str(raw.get("excerpt") or raw.get("content") or "").strip()
+        url = _normalize_optional_string(raw.get("url"))
+        key = (str(raw.get("id") or title).strip() or title, url or "", excerpt)
+        if key in seen:
+            continue
+        seen.add(key)
+        label = f"[{len(citations) + 1}]"
+        citation = {
+            "label": label,
+            "id": str(raw.get("id") or title).strip() or title,
+            "title": title,
+            "excerpt": _truncate_text(excerpt, 240),
+            "url": url,
+            "source_kind": str(raw.get("source_kind") or "external"),
+            "metadata": dict(raw.get("metadata") or {}),
+        }
+        citations.append(citation)
+        if len(citations) >= limit:
+            break
+    citation_block = "\n".join(_render_citation(citation) for citation in citations)
+    return {"citations": citations, "citation_block": citation_block}
+
+
+def validate_grounding_web_search(tool_input: dict[str, Any], _: ToolContext) -> ValidationOutcome:
+    if not str(tool_input.get("query") or "").strip():
+        return ValidationOutcome(False, "query must be non-empty")
+    return ValidationOutcome(True)
+
+
+async def grounding_web_search_tool(tool_input: dict[str, Any], _: ToolContext) -> dict[str, Any]:
+    query = str(tool_input["query"]).strip()
+    limit = max(1, min(int(tool_input.get("limit", 5)), 8))
+    encoded = urllib.parse.urlencode({"q": query})
+    url = f"{_GROUNDING_SEARCH_BASE_URL}?{encoded}"
+
+    def search() -> dict[str, Any]:
+        request = urllib.request.Request(url, headers={"User-Agent": "weavert/0.1"})
+        with _grounding_urlopen(request, timeout=10) as response:
+            body = response.read().decode("utf-8", errors="replace")
+        results: list[dict[str, Any]] = []
+        for match in re.finditer(
+            r'<a[^>]*class="result__a"[^>]*href="(?P<href>[^"]+)"[^>]*>(?P<title>.*?)</a>',
+            body,
+        ):
+            title = html.unescape(_HTML_TAG_RE.sub("", match.group("title"))).strip()
+            href = _normalize_grounding_url(match.group("href"))
+            if href is None or _grounding_url_validation_error(href) is not None:
+                continue
+            results.append({"title": title or href, "url": href})
+            if len(results) >= limit:
+                break
+        return {"query": query, "results": results}
+
+    return await asyncio.to_thread(search)
+
+
+def validate_grounding_web_fetch(tool_input: dict[str, Any], _: ToolContext) -> ValidationOutcome:
+    url = _normalize_grounding_url(tool_input.get("url"))
+    if url is None:
+        return ValidationOutcome(False, "Only http:// and https:// URLs are supported")
+    validation_error = _grounding_url_validation_error(url)
+    if validation_error is not None:
+        return ValidationOutcome(False, validation_error)
+    return ValidationOutcome(True)
+
+
+async def grounding_web_fetch_tool(tool_input: dict[str, Any], _: ToolContext) -> dict[str, Any]:
+    timeout = max(1, int(tool_input.get("timeout_ms", 10_000))) / 1000
+    max_chars = max(500, min(int(tool_input.get("max_chars", _DEFAULT_FETCH_CHARS)), 32_000))
+    url = _normalize_grounding_url(tool_input.get("url"))
+    if url is None:
+        raise ValueError("Only http:// and https:// URLs are supported")
+    validation_error = _grounding_url_validation_error(url)
+    if validation_error is not None:
+        raise ValueError(validation_error)
+
+    def fetch() -> dict[str, Any]:
+        request = urllib.request.Request(url, headers={"User-Agent": "weavert/0.1"})
+        with _grounding_urlopen(request, timeout=timeout) as response:
+            raw = response.read(_MAX_FETCH_BYTES + 1)
+            content_type = response.headers.get_content_type()
+            body = raw.decode("utf-8", errors="replace")
+            normalized = _normalize_remote_text(body, content_type=content_type)
+            truncated = len(raw) > _MAX_FETCH_BYTES or len(normalized) > max_chars
+            title = _extract_html_title(body) if "html" in content_type else None
+            resolved_url = _normalize_grounding_url(_response_url(response)) or url
+            return {
+                "url": resolved_url,
+                "status": getattr(response, "status", 200),
+                "content_type": content_type,
+                "title": title,
+                "content": _truncate_text(normalized, max_chars),
+                "truncated": truncated,
+            }
+
+    return await asyncio.to_thread(fetch)
+
+
+def _inline_candidates(items: Any) -> tuple[_GroundingCandidate, ...]:
+    if not isinstance(items, list):
+        return ()
+    candidates: list[_GroundingCandidate] = []
+    for index, raw in enumerate(items, start=1):
+        if not isinstance(raw, Mapping):
+            continue
+        content = str(raw.get("content") or raw.get("excerpt") or "").strip()
+        if not content:
+            continue
+        title = str(raw.get("title") or raw.get("id") or f"Source {index}").strip() or f"Source {index}"
+        candidate_id = str(raw.get("id") or f"source-{index}").strip() or f"source-{index}"
+        metadata = dict(raw.get("metadata") or {})
+        candidates.append(
+            _GroundingCandidate(
+                candidate_id=candidate_id,
+                title=title,
+                content=content,
+                url=_normalize_optional_string(raw.get("url")),
+                source_kind=str(raw.get("source_kind") or "external"),
+                metadata=metadata,
+            )
+        )
+    return tuple(candidates)
+
+
+def _memory_candidates(context: ToolContext, scope_value: Any) -> tuple[_GroundingCandidate, ...]:
+    services = context.runtime_services
+    if services is None:
+        return ()
+    try:
+        memory_service = services.resolve_memory_service()
+    except Exception:
+        return ()
+    if memory_service is None:
+        return ()
+    resolver = getattr(memory_service, "context_for_scope", None)
+    manager = getattr(memory_service, "manager", None)
+    provider = getattr(manager, "provider", None)
+    if not callable(resolver) or provider is None or not hasattr(provider, "list_documents"):
+        return ()
+    try:
+        scope = _coerce_memory_scope(scope_value)
+        resolved_scope = resolver(
+            session_id=context.session_id,
+            scope=scope,
+            cwd=context.cwd,
+        )
+        documents = provider.list_documents(resolved_scope)
+    except Exception:
+        return ()
+    return tuple(
+        _candidate_from_memory_document(document, resolved_scope.memory_root)
+        for document in documents
+        if _looks_like_memory_document(document)
+    )
+
+
+def _looks_like_memory_document(document: Any) -> bool:
+    scope = getattr(document, "scope", None)
+    return (
+        hasattr(document, "path")
+        and hasattr(document, "title")
+        and hasattr(document, "metadata")
+        and hasattr(document, "kind")
+        and hasattr(scope, "value")
+        and bool(str(getattr(document, "content", "") or "").strip())
+    )
+
+
+def _candidate_from_memory_document(document: Any, memory_root: Path) -> _GroundingCandidate:
+    try:
+        relative_path = document.path.relative_to(memory_root).as_posix()
+    except ValueError:
+        relative_path = document.path.name
+    metadata = dict(document.metadata)
+    metadata.setdefault("memory_scope", document.scope.value)
+    metadata.setdefault("memory_path", relative_path)
+    metadata.setdefault("memory_kind", document.kind)
+    return _GroundingCandidate(
+        candidate_id=relative_path,
+        title=document.title,
+        content=document.content,
+        url=None,
+        source_kind="memory",
+        metadata=metadata,
+    )
+
+
+def _coerce_memory_scope(value: Any) -> MemoryScope:
+    normalized = str(value or MemoryScope.PROJECT.value).strip() or MemoryScope.PROJECT.value
+    try:
+        return MemoryScope(normalized)
+    except ValueError:
+        return MemoryScope.PROJECT
+
+
+def _candidate_score(query_tokens: set[str], candidate: _GroundingCandidate) -> float:
+    combined = f"{candidate.title} {candidate.content}"
+    combined_tokens = _tokenize(combined)
+    if not query_tokens:
+        return 0.0
+    overlap = len(query_tokens & combined_tokens)
+    if overlap <= 0:
+        lowered_query = " ".join(sorted(query_tokens))
+        if lowered_query and lowered_query not in combined.lower():
+            return 0.0
+    title_overlap = len(query_tokens & _tokenize(candidate.title))
+    tag_overlap = len(query_tokens & _tokenize(" ".join(_string_values(candidate.metadata.get("tags")))))
+    source_bonus = 0.25 if candidate.source_kind == "memory" else 0.0
+    return float(overlap) + (0.5 * float(title_overlap)) + (0.25 * float(tag_overlap)) + source_bonus
+
+
+def _best_excerpt(query_tokens: set[str], content: str, *, limit: int = 280) -> str:
+    normalized = " ".join(content.strip().split())
+    if not normalized:
+        return ""
+    for chunk in re.split(r"(?<=[.!?])\s+|\n+", normalized):
+        candidate = chunk.strip()
+        if not candidate:
+            continue
+        lowered = candidate.lower()
+        if any(token in lowered for token in query_tokens):
+            return _truncate_text(candidate, limit)
+    return _truncate_text(normalized, limit)
+
+
+def _render_citation(citation: Mapping[str, Any]) -> str:
+    title = str(citation.get("title") or citation.get("id") or "Untitled source").strip() or "Untitled source"
+    excerpt = str(citation.get("excerpt") or "").strip()
+    url = _normalize_optional_string(citation.get("url"))
+    suffix = f" — {url}" if url else ""
+    if excerpt:
+        return f"{citation['label']} {title}{suffix}: {excerpt}"
+    return f"{citation['label']} {title}{suffix}"
+
+
+def _normalize_grounding_url(value: Any) -> str | None:
+    candidate = _normalize_optional_string(value)
+    if candidate is None:
+        return None
+    candidate = html.unescape(candidate)
+    if candidate.startswith("//"):
+        candidate = f"https:{candidate}"
+    elif candidate.startswith("/"):
+        candidate = urllib.parse.urljoin(_GROUNDING_SEARCH_BASE_URL, candidate)
+    parsed = urllib.parse.urlparse(candidate)
+    scheme = parsed.scheme.lower()
+    if scheme not in {"http", "https"} or not parsed.netloc:
+        return None
+    hostname = (parsed.hostname or "").rstrip(".").lower()
+    if hostname in _GROUNDING_REDIRECT_HOSTS and parsed.path in {"/l", "/l/"}:
+        redirect_targets = urllib.parse.parse_qs(parsed.query).get("uddg")
+        if redirect_targets:
+            return _normalize_grounding_url(redirect_targets[0])
+    return urllib.parse.urlunparse(parsed._replace(fragment=""))
+
+
+def _grounding_url_validation_error(url: str) -> str | None:
+    parsed = urllib.parse.urlparse(url)
+    hostname = (parsed.hostname or "").rstrip(".").lower()
+    if not hostname:
+        return "Grounding fetch requires a public web hostname"
+    if parsed.username is not None or parsed.password is not None:
+        return "Grounding fetch does not allow embedded URL credentials"
+    if hostname in _GROUNDING_BLOCKED_HOSTS or any(
+        hostname.endswith(suffix) for suffix in _GROUNDING_BLOCKED_HOST_SUFFIXES
+    ):
+        return "Grounding fetch only supports public web hosts"
+    try:
+        address = ipaddress.ip_address(hostname)
+    except ValueError:
+        if "." not in hostname:
+            return "Grounding fetch only supports public web hosts"
+        resolution_is_public = _grounding_hostname_resolves_publicly(hostname)
+        if resolution_is_public is False:
+            return "Grounding fetch only supports public web hosts"
+        return None
+    if not address.is_global:
+        return "Grounding fetch only supports public web hosts"
+    return None
+
+
+@lru_cache(maxsize=256)
+def _grounding_hostname_resolves_publicly(hostname: str) -> bool | None:
+    try:
+        resolutions = socket.getaddrinfo(
+            hostname,
+            None,
+            type=socket.SOCK_STREAM,
+            proto=socket.IPPROTO_TCP,
+        )
+    except OSError:
+        return None
+    saw_address = False
+    for _family, _kind, _proto, _canonname, sockaddr in resolutions:
+        if not sockaddr:
+            continue
+        try:
+            address = ipaddress.ip_address(str(sockaddr[0]).strip())
+        except ValueError:
+            continue
+        saw_address = True
+        if not address.is_global:
+            return False
+    return True if saw_address else None
+
+
+class _SafeGroundingRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        normalized = _normalize_grounding_url(newurl)
+        if normalized is None:
+            raise urllib.error.HTTPError(newurl, code, "Only http:// and https:// URLs are supported", headers, fp)
+        validation_error = _grounding_url_validation_error(normalized)
+        if validation_error is not None:
+            raise urllib.error.HTTPError(normalized, code, validation_error, headers, fp)
+        return super().redirect_request(req, fp, code, msg, headers, normalized)
+
+
+def _grounding_urlopen(request: urllib.request.Request, *, timeout: float | int):
+    opener = urllib.request.build_opener(_SafeGroundingRedirectHandler())
+    return opener.open(request, timeout=timeout)
+
+
+def _response_url(response: Any) -> str | None:
+    resolver = getattr(response, "geturl", None)
+    if callable(resolver):
+        return _normalize_optional_string(resolver())
+    return getattr(response, "url", None)
+
+
+def _normalize_remote_text(body: str, *, content_type: str) -> str:
+    normalized = body
+    if "html" in content_type:
+        normalized = _HTML_SCRIPT_STYLE_RE.sub(" ", normalized)
+        normalized = _HTML_TAG_RE.sub(" ", normalized)
+        normalized = html.unescape(normalized)
+    return _WHITESPACE_RE.sub(" ", normalized).strip()
+
+
+def _extract_html_title(body: str) -> str | None:
+    match = _HTML_TITLE_RE.search(body)
+    if not match:
+        return None
+    title = html.unescape(_HTML_TAG_RE.sub("", match.group("title"))).strip()
+    return title or None
+
+
+def _truncate_text(value: str, limit: int) -> str:
+    normalized = " ".join(value.strip().split())
+    if len(normalized) <= limit:
+        return normalized
+    return normalized[: limit - 3].rstrip() + "..."
+
+
+def _normalize_optional_string(value: Any) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def _string_values(value: Any) -> tuple[str, ...]:
+    if isinstance(value, str):
+        return (value,)
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return tuple(str(item) for item in value if str(item).strip())
+    return ()
+
+
+def _tokenize(text: str) -> set[str]:
+    return {
+        token
+        for token in re.findall(r"[a-z0-9]+", text.lower())
+        if len(token) > 2 and token not in _STOPWORDS
+    }
+
+
+__all__ = [
+    "grounding_web_fetch_tool",
+    "grounding_web_search_tool",
+    "prepare_citations_tool",
+    "retrieve_context_tool",
+    "validate_grounding_web_fetch",
+    "validate_grounding_web_search",
+    "validate_prepare_citations_tool",
+    "validate_retrieve_context_tool",
+]

weavert_kit_chat-0.1.0/src/weavert_kit_chat.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: weavert-kit-chat
+Version: 0.1.0
+Summary: Chat-oriented product kit for extracted WeaveRT scenario packs.
+Author: WeaveRT Maintainers
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/xyz2b/weave-ai-runtime
+Project-URL: Documentation, https://github.com/xyz2b/weave-ai-runtime/tree/main/docs
+Project-URL: Repository, https://github.com/xyz2b/weave-ai-runtime
+Project-URL: Issues, https://github.com/xyz2b/weave-ai-runtime/issues
+Keywords: weavert,agents,ai,product-kit,scenario-pack
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: weavert<0.2.0,>=0.1.0
+Requires-Dist: weavert-kit-common-retrieval<0.2.0,>=0.1.0
+Requires-Dist: weavert-kit-common-web<0.2.0,>=0.1.0
+
+# Chat Product Kit
+
+Canonical import root: `weavert_kit_chat`
+
+## What this package owns
+
+- the `weavert-scenario-chat` scenario pack
+- chat-oriented product-profile defaults layered on shared grounding packages
+
+## Canonical names
+
+- install name: `weavert-kit-chat`
+- import root: `weavert_kit_chat`
+- runtime activation: `weavert-scenario-chat`
+
+The public install name stays separate from the runtime scenario-pack activation name.
+
+## Shared packages it composes
+
+- `weavert_kit_common_retrieval`
+- `weavert_kit_common_web`
+
+## See also
+
+- `../README.md`
+- `../common/README.md`
+- `../../../docs/guides/use-scenario-packs.md`
+- `../../../docs/introduction/use-cases.md`

weavert_kit_chat-0.1.0/src/weavert_kit_chat.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/weavert_kit_chat/__init__.py
+src/weavert_kit_chat/_builtins.py
+src/weavert_kit_chat/_tool_impls.py
+src/weavert_kit_chat.egg-info/PKG-INFO
+src/weavert_kit_chat.egg-info/SOURCES.txt
+src/weavert_kit_chat.egg-info/dependency_links.txt
+src/weavert_kit_chat.egg-info/requires.txt
+src/weavert_kit_chat.egg-info/top_level.txt

weavert_kit_chat-0.1.0/src/weavert_kit_chat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

weavert_kit_chat-0.1.0/src/weavert_kit_chat.egg-info/requires.txt

@@ -0,0 +1,3 @@
+weavert<0.2.0,>=0.1.0
+weavert-kit-common-retrieval<0.2.0,>=0.1.0
+weavert-kit-common-web<0.2.0,>=0.1.0

weavert_kit_chat-0.1.0/src/weavert_kit_chat.egg-info/top_level.txt

@@ -0,0 +1 @@
+weavert_kit_chat