weavert-kit-common-web-research 0.1.0__tar.gz

weavert_kit_common_web_research-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: weavert-kit-common-web-research
+Version: 0.1.0
+Summary: Unified AI-first web_research and read-only web primitive kit surfaces for WeaveRT product kits.
+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,shared-kit
+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-web-research<0.2.0,>=0.1.0
+
+# Web Research Common Kit
+
+Canonical import root: `weavert_kit_common_web_research`
+
+## What this package owns
+
+- the unified public `web_research` entrypoint for read-only public-web information retrieval
+- low-level `web_search`, single-page `web_fetch`, and `web_find` primitives backed by `weavert-web-research`
+- a package-owned goal-driven research loop behind `web_research` that plans queries, selects pages, evaluates evidence coverage, and stops with explicit reasons
+- the package-owned `web-searcher` delegated worker reserved for bounded implementation-period fallback paths
+- first-party research profiles: `general`, `coding`, `business`, `academic`, `legal_compliance`, and `product_shopping`
+- common result envelopes with sources, evidence, conflicts, gaps, freshness, provider metadata, research trace, and profile facets
+
+## Canonical names
+
+- package root: `packages/product-kits/common/web-research`
+- install name: `weavert-kit-common-web-research`
+- import root: `weavert_kit_common_web_research`
+- runtime activation: `weavert-shared-web-research`
+
+## Boundary
+
+Use `web_research` for goal-driven AI-first research and pass `profile="coding"` or another supported profile when the scenario needs profile-specific source ranking or facets. `web_research` is the supported path for multi-page source discovery and inspection: it derives bounded queries from the objective, ranks candidate pages, inspects ledger-verified sources, reports gaps or conflicts, and exposes loop decisions in `research_trace` and `trace_summary`. Use low-level `web_fetch` only for one explicit page at a time; callers that need manual multi-page inspection should issue repeated single-page fetches.
+
+This package is read-only. Browser navigation, clicks, form filling, authenticated browsing, and DOM interaction remain browser-bridge responsibilities.
+
+## Search Provider Selection
+
+Public tool names stay stable: callers continue to use `web_research`, `web_search`, `web_fetch`, and `web_find`. Search provider selection is handled by the shared `weavert-web-research` core.
+
+- `google-search`: set `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_CX`; optionally set `WEAVERT_WEB_SEARCH_PROVIDER=google-search`.
+- `brave-search`: set `BRAVE_SEARCH_API_KEY` or `WEAVERT_BRAVE_SEARCH_API_KEY`; optionally set `WEAVERT_WEB_SEARCH_PROVIDER=brave-search`.
+- `bing-grounding`: set `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`, `BING_PROJECT_CONNECTION_ID`, and `AGENT_TOKEN`; optionally set `WEAVERT_WEB_SEARCH_PROVIDER=bing-grounding`.
+- `duckduckgo-html`: no-credential fallback. It does not expose a stable freshness filter through this adapter.
+
+Bing grounding uses Azure AI Foundry Responses API `bing_grounding` and normalizes stable public URL citations into the shared result shape. It is not the retired Bing Search API v7 endpoint. Google and Brave map domain constraints into provider query operators where supported, while Bing grounding and DuckDuckGo report those controls as framework-filtered. The shared core still revalidates accepted result URLs against allowed domains, blocked domains, and public-host policy. Freshness semantics are provider-specific: Google uses approximate `dateRestrict`, Brave uses its `freshness` parameter, Bing grounding maps supported 1/7/30 day freshness windows, and DuckDuckGo reports freshness as unsupported.
+
+## Research Profiles and Quality Signals
+
+`web_research` applies profile strategy before inspecting pages. Coding prioritizes official documentation, release notes, changelogs, source repositories, and issue trackers, with facets for API names, versions, compatibility notes, and breaking changes. Legal compliance prioritizes statutes, regulations, standards, and official guidance, and preserves jurisdiction, authority, freshness, and effective-date gaps. Business research favors company sources, filings, announcements, credible news, reviews, competitors, timelines, comparison axes, and market claims. Academic research favors papers, publishers, institutions, preprints, methods, experiments, conclusions, and citation metadata. Product shopping favors official specs, current prices, reviews, alternatives, comparison axes, and purchase-risk signals.
+
+Candidate sources receive traceable quality metadata before fetch: objective relevance, profile priority, provider metadata, freshness signals, preferred or allowed domains, duplicate clusters, and deterministic tie-breaking by domain and URL. After inspection, ledger evidence keeps source class and quality metadata so callers and tests can explain why a source was selected.
+
+## Claims, Conflicts, Gaps, and Limits
+
+Claim annotations are accepted only when they bind to an inspected ledger source, page, or evidence item. Unbound annotations are dropped and traced. Rule-derived dates, versions, prices, numbers, source-type hints, and duplicate signals appear as `auxiliary_signals`; they help diagnostics and facets but do not prove claim correctness.
+
+Conflicting ledger-bound claims are projected into `conflicts`. Unresolved conflicts lower confidence and produce `stop_reason="unresolved_conflict"`; resolved conflicts keep a resolution rationale when stronger evidence is identified. Gaps describe missing preferred evidence, unsupported freshness, provider fallback, policy blocks, or partial results.
+
+Remaining limits are explicit: this kit does not drive a browser, click through pages, authenticate, inspect local workspaces, run shell-assisted searches, or guarantee truth beyond inspected public evidence. Host-level browser bridges, local workspace search, and shell tools remain separate surfaces.
+
+## See also
+
+- `../README.md`
+- `../../../framework-packs/capabilities/web-research/README.md`

weavert_kit_common_web_research-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Web Research Common Kit
+
+Canonical import root: `weavert_kit_common_web_research`
+
+## What this package owns
+
+- the unified public `web_research` entrypoint for read-only public-web information retrieval
+- low-level `web_search`, single-page `web_fetch`, and `web_find` primitives backed by `weavert-web-research`
+- a package-owned goal-driven research loop behind `web_research` that plans queries, selects pages, evaluates evidence coverage, and stops with explicit reasons
+- the package-owned `web-searcher` delegated worker reserved for bounded implementation-period fallback paths
+- first-party research profiles: `general`, `coding`, `business`, `academic`, `legal_compliance`, and `product_shopping`
+- common result envelopes with sources, evidence, conflicts, gaps, freshness, provider metadata, research trace, and profile facets
+
+## Canonical names
+
+- package root: `packages/product-kits/common/web-research`
+- install name: `weavert-kit-common-web-research`
+- import root: `weavert_kit_common_web_research`
+- runtime activation: `weavert-shared-web-research`
+
+## Boundary
+
+Use `web_research` for goal-driven AI-first research and pass `profile="coding"` or another supported profile when the scenario needs profile-specific source ranking or facets. `web_research` is the supported path for multi-page source discovery and inspection: it derives bounded queries from the objective, ranks candidate pages, inspects ledger-verified sources, reports gaps or conflicts, and exposes loop decisions in `research_trace` and `trace_summary`. Use low-level `web_fetch` only for one explicit page at a time; callers that need manual multi-page inspection should issue repeated single-page fetches.
+
+This package is read-only. Browser navigation, clicks, form filling, authenticated browsing, and DOM interaction remain browser-bridge responsibilities.
+
+## Search Provider Selection
+
+Public tool names stay stable: callers continue to use `web_research`, `web_search`, `web_fetch`, and `web_find`. Search provider selection is handled by the shared `weavert-web-research` core.
+
+- `google-search`: set `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_CX`; optionally set `WEAVERT_WEB_SEARCH_PROVIDER=google-search`.
+- `brave-search`: set `BRAVE_SEARCH_API_KEY` or `WEAVERT_BRAVE_SEARCH_API_KEY`; optionally set `WEAVERT_WEB_SEARCH_PROVIDER=brave-search`.
+- `bing-grounding`: set `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`, `BING_PROJECT_CONNECTION_ID`, and `AGENT_TOKEN`; optionally set `WEAVERT_WEB_SEARCH_PROVIDER=bing-grounding`.
+- `duckduckgo-html`: no-credential fallback. It does not expose a stable freshness filter through this adapter.
+
+Bing grounding uses Azure AI Foundry Responses API `bing_grounding` and normalizes stable public URL citations into the shared result shape. It is not the retired Bing Search API v7 endpoint. Google and Brave map domain constraints into provider query operators where supported, while Bing grounding and DuckDuckGo report those controls as framework-filtered. The shared core still revalidates accepted result URLs against allowed domains, blocked domains, and public-host policy. Freshness semantics are provider-specific: Google uses approximate `dateRestrict`, Brave uses its `freshness` parameter, Bing grounding maps supported 1/7/30 day freshness windows, and DuckDuckGo reports freshness as unsupported.
+
+## Research Profiles and Quality Signals
+
+`web_research` applies profile strategy before inspecting pages. Coding prioritizes official documentation, release notes, changelogs, source repositories, and issue trackers, with facets for API names, versions, compatibility notes, and breaking changes. Legal compliance prioritizes statutes, regulations, standards, and official guidance, and preserves jurisdiction, authority, freshness, and effective-date gaps. Business research favors company sources, filings, announcements, credible news, reviews, competitors, timelines, comparison axes, and market claims. Academic research favors papers, publishers, institutions, preprints, methods, experiments, conclusions, and citation metadata. Product shopping favors official specs, current prices, reviews, alternatives, comparison axes, and purchase-risk signals.
+
+Candidate sources receive traceable quality metadata before fetch: objective relevance, profile priority, provider metadata, freshness signals, preferred or allowed domains, duplicate clusters, and deterministic tie-breaking by domain and URL. After inspection, ledger evidence keeps source class and quality metadata so callers and tests can explain why a source was selected.
+
+## Claims, Conflicts, Gaps, and Limits
+
+Claim annotations are accepted only when they bind to an inspected ledger source, page, or evidence item. Unbound annotations are dropped and traced. Rule-derived dates, versions, prices, numbers, source-type hints, and duplicate signals appear as `auxiliary_signals`; they help diagnostics and facets but do not prove claim correctness.
+
+Conflicting ledger-bound claims are projected into `conflicts`. Unresolved conflicts lower confidence and produce `stop_reason="unresolved_conflict"`; resolved conflicts keep a resolution rationale when stronger evidence is identified. Gaps describe missing preferred evidence, unsupported freshness, provider fallback, policy blocks, or partial results.
+
+Remaining limits are explicit: this kit does not drive a browser, click through pages, authenticate, inspect local workspaces, run shell-assisted searches, or guarantee truth beyond inspected public evidence. Host-level browser bridges, local workspace search, and shell tools remain separate surfaces.
+
+## See also
+
+- `../README.md`
+- `../../../framework-packs/capabilities/web-research/README.md`

weavert_kit_common_web_research-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "weavert-kit-common-web-research"
+version = "0.1.0"
+description = "Unified AI-first web_research and read-only web primitive kit surfaces for WeaveRT product kits."
+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-web-research>=0.1.0,<0.2.0",
+]
+keywords = ["weavert", "agents", "ai", "product-kit", "shared-kit"]
+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_common_web_research-0.1.0/setup.cfg

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

weavert_kit_common_web_research-0.1.0/src/weavert_kit_common_web_research/__init__.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from weavert.package_system.protocols import RuntimePackageManifest
+from weavert.extension_contracts.scenario_runtime_packs import (
+    ReferenceSharedPackageShape,
+    build_reference_shared_package_manifest,
+)
+
+from ._builtins import (
+    WEB_RESEARCH_TOOLS,
+    WEB_RESEARCH_WORKER_AGENTS,
+    web_research_builtin_tools,
+    web_research_worker_builtin_agents,
+)
+from ._tool_impls import (
+    web_fetch_tool,
+    web_find_tool,
+    web_search_tool,
+    validate_web_fetch,
+    validate_web_find,
+    validate_web_search,
+    validate_web_research,
+    web_research_tool,
+)
+
+REFERENCE_SHARED_PACKAGE_SHAPE = ReferenceSharedPackageShape(
+    package_name="weavert-shared-web-research",
+    capability_key="weavert.reference.shared.web_research",
+    description="Reference shared package for AI-first web_research plus low-level read-only web primitives.",
+    shared_surface_family="web-research",
+    intended_profiles=(
+        "chat",
+        "coding",
+        "local_assistant",
+        "business",
+        "academic",
+        "legal_compliance",
+        "product_shopping",
+    ),
+    surfaces=(
+        "AI-first bounded web_research entrypoint",
+        "read-only web search",
+        "single-page remote fetch",
+        "page-local web evidence finding",
+        "bounded multi-page inspection behind web_research",
+        "HTTP-aware web helpers",
+    ),
+    tool_ids=WEB_RESEARCH_TOOLS,
+    agent_ids=WEB_RESEARCH_WORKER_AGENTS,
+    notes=(
+        "Scenario packs should recommend web_research as the public web research entrypoint.",
+        "Scenario packs set default research profiles without changing public web tool names.",
+        "Low-level primitives remain available for explicit search, fetch, and page-local find flows.",
+        "web-searcher is a package-owned delegated worker behind web_research, not the recommended public path.",
+        "The default posture stays read-only and web research even when external web is enabled.",
+        "Browser navigation or interaction still requires a separate browser bridge package.",
+    ),
+)
+
+
+def reference_shared_package_shapes() -> tuple[ReferenceSharedPackageShape, ...]:
+    return (REFERENCE_SHARED_PACKAGE_SHAPE,)
+
+
+def reference_shared_package_shape(name: str | None = None) -> ReferenceSharedPackageShape:
+    normalized = REFERENCE_SHARED_PACKAGE_SHAPE.package_name if name is None else str(name)
+    if normalized in {
+        REFERENCE_SHARED_PACKAGE_SHAPE.package_name,
+        REFERENCE_SHARED_PACKAGE_SHAPE.capability_key,
+    }:
+        return REFERENCE_SHARED_PACKAGE_SHAPE
+    raise KeyError(f"Unknown web shared package shape: {name}")
+
+
+def reference_shared_package_manifest() -> RuntimePackageManifest:
+    return build_reference_shared_package_manifest(
+        REFERENCE_SHARED_PACKAGE_SHAPE,
+        builtin_tools=web_research_builtin_tools,
+        builtin_agents=web_research_worker_builtin_agents,
+    )
+
+
+def reference_shared_package_manifests() -> tuple[RuntimePackageManifest, ...]:
+    return (reference_shared_package_manifest(),)
+
+
+__all__ = [
+    "WEB_RESEARCH_TOOLS",
+    "REFERENCE_SHARED_PACKAGE_SHAPE",
+    "WEB_RESEARCH_WORKER_AGENTS",
+    "web_fetch_tool",
+    "web_find_tool",
+    "web_search_tool",
+    "reference_shared_package_manifest",
+    "reference_shared_package_manifests",
+    "reference_shared_package_shape",
+    "reference_shared_package_shapes",
+    "validate_web_fetch",
+    "validate_web_find",
+    "validate_web_search",
+    "validate_web_research",
+    "web_research_tool",
+    "web_research_worker_builtin_agents",
+]