@tasksai/install 0.1.29 → 0.1.31

package/README.md

@@ -75,3 +75,15 @@ folder. The save tool supports `.docx` and Markdown output, sanitizes filenames,
 and avoids overwriting existing files unless explicitly told to overwrite.
 Generated document content is handled by the customer's AI framework and local
 MCP runtime; it is not sent to TasksAI websites or APIs.
+
+## Realtor jurisdiction sources
+
+For jurisdiction-sensitive RealtorTasksAI workflows, the local runtime sends
+only the selected skill ID and general state, county, city, public-authority,
+and MLS labels to the TasksAI API. It never sends the user's prompt, property
+address, client facts, uploaded records, or generated document.
+
+The API returns a reviewed source pack when one exists. If it does not, the
+licensed runtime can request a controlled official-web lookup. Live results are
+cached, source-linked, and visibly labeled `provisional`; they never substitute
+for private MLS rules, brokerage policy, approved forms, or professional review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tasksai/install",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Shared TasksAI MCP installer CLI",
   "type": "module",
   "bin": {

package/runtime/server.py

@@ -125,7 +125,7 @@ if not LICENSE_KEY:
     print("Find your key in your purchase confirmation email.", file=sys.stderr, flush=True)
     sys.exit(1)
 
-SERVER_VERSION = "2.4.5"
+SERVER_VERSION = "2.5.0"
 
 AUTH_HEADERS = {
     "Authorization":    f"Bearer {LICENSE_KEY}",
@@ -509,8 +509,8 @@ async def api_get(path):
         return resp.json()
 
 
-async def api_post(path, payload):
-    async with httpx.AsyncClient(timeout=10.0) as client:
+async def api_post(path, payload, *, timeout=10.0):
+    async with httpx.AsyncClient(timeout=timeout) as client:
         resp = await client.post(
             f"{API_BASE}{path}",
             json=payload,
@@ -523,20 +523,58 @@ async def api_post(path, payload):
 def jurisdiction_sources_path(arguments):
     """Build a metadata-only source lookup path without customer or property data."""
     skill_id = (arguments.get("skill_id") or "").strip()
-    state = (arguments.get("state") or "").strip()
+    state = general_authority_label(arguments.get("state"), "state")
     if not skill_id:
         raise ValueError("skill_id is required.")
 
     params = {"skill_id": skill_id}
     if state:
         params["state"] = state
-    for field in ("county", "locality", "district"):
-        value = (arguments.get(field) or "").strip()
+    for field in ("county", "locality", "district", "mls"):
+        value = general_authority_label(arguments.get(field), field)
         if value:
             params[field] = value
     return f"/v1/skills/jurisdiction-sources?{urlencode(params)}"
 
 
+_GENERAL_AUTHORITY_LABEL = re.compile(r"^[A-Za-z0-9 .,'&()/-]{1,240}$")
+_LIKELY_STREET_ADDRESS = re.compile(
+    r"^\d+\s+.+\b(?:street|st|avenue|ave|road|rd|drive|dr|lane|ln|boulevard|blvd|court|ct|way)\b",
+    re.IGNORECASE,
+)
+
+
+def general_authority_label(value, field):
+    """Normalize a public authority label and reject likely customer data."""
+    normalized = " ".join(str(value or "").strip().split())
+    if not normalized:
+        return None
+    if (
+        not _GENERAL_AUTHORITY_LABEL.fullmatch(normalized)
+        or _LIKELY_STREET_ADDRESS.search(normalized)
+    ):
+        raise ValueError(
+            f"{field} must be a general authority label, not an address or customer record."
+        )
+    return normalized
+
+
+def jurisdiction_research_payload(arguments):
+    """Build the privacy-safe research request sent only after reviewed lookup misses."""
+    payload = {}
+    for field in ("skill_id", "state", "county", "locality", "district", "mls"):
+        value = (
+            (arguments.get(field) or "").strip()
+            if field == "skill_id"
+            else general_authority_label(arguments.get(field), field)
+        )
+        if value:
+            payload[field] = value
+    if not payload.get("skill_id") or not payload.get("state"):
+        raise ValueError("skill_id and state are required for live jurisdiction research.")
+    return payload
+
+
 def format_jurisdiction_source_pack(pack):
     """Render the public source pack as compact instructions for the local AI."""
     status = pack.get("status", "unsupported")
@@ -548,6 +586,7 @@ def format_jurisdiction_source_pack(pack):
         f"- Skill: `{pack.get('skill_id', '')}`",
         f"- Registry reviewed: {pack.get('registry_reviewed_on', 'not supplied')}",
         f"- Registry refresh due: {pack.get('registry_refresh_due_on', 'not supplied')}",
+        f"- Resolution: **{pack.get('resolution_source', 'packaged')}**",
     ]
     if pack.get("state_name"):
         lines.append(f"- State: {pack['state_name']} ({pack.get('state_code', '')})")
@@ -566,6 +605,8 @@ def format_jurisdiction_source_pack(pack):
         lines.extend(["", "## Sources"])
         for source in sources:
             effective = source.get("effective_date") or "not specified"
+            verification = source.get("verification_status", "reviewed")
+            date_label = "Machine researched" if verification == "machine_researched" else "Reviewed"
             lines.extend(
                 [
                     "",
@@ -573,7 +614,8 @@ def format_jurisdiction_source_pack(pack):
                     f"- Authority: {source.get('authority', '')}",
                     f"- Jurisdiction: {source.get('jurisdiction', '')} ({source.get('scope_type', 'scope not supplied')})",
                     f"- Effective date: {effective}",
-                    f"- Reviewed: {source.get('reviewed_on', '')}",
+                    f"- Verification: {verification}",
+                    f"- {date_label}: {source.get('reviewed_on', '')}",
                     f"- Refresh due: {source.get('refresh_due_on', '')}",
                     f"- URL: {source.get('url', '')}",
                     f"- Use: {source.get('purpose', '')}",
@@ -1672,8 +1714,9 @@ def build_tools(prefix, product_name, occupation):
             Tool(
                 name=f"{prefix}_jurisdiction_sources",
                 description=(
-                    f"Retrieve the curated current jurisdiction-and-authority source pack for a jurisdiction-sensitive {product_name} workflow. "
+                    f"Retrieve the current jurisdiction-and-authority sources for a jurisdiction-sensitive {product_name} workflow. "
                     "Use after the applicable state is known and before applying state, local, district, regulator, form, or policy requirements. "
+                    "For RealtorTasksAI, a missing reviewed pack can trigger a licensed, privacy-safe official-web lookup whose results are explicitly provisional. "
                     "Send only the skill ID and general authority labels; never send an address, person name, student or client facts, documents, or generated content."
                 ),
                 inputSchema={
@@ -1699,6 +1742,10 @@ def build_tools(prefix, product_name, occupation):
                             "type": "string",
                             "description": "Optional public authority or school-district name only; do not include a person, student, or record identifier.",
                         },
+                        "mls": {
+                            "type": "string",
+                            "description": "Optional MLS or Realtor-association name only; never send credentials, listing data, or member-only content.",
+                        },
                     },
                     "required": ["skill_id"],
                 },
@@ -1905,6 +1952,24 @@ async def call_tool(name, arguments):
         }:
             path = jurisdiction_sources_path(arguments or {})
             result = await api_get(path)
+            if (
+                prefix == "realtortasksai"
+                and (arguments or {}).get("state")
+                and result.get("status") not in {"ready", "provisional"}
+            ):
+                try:
+                    result = await api_post(
+                        "/v1/skills/jurisdiction-research",
+                        jurisdiction_research_payload(arguments or {}),
+                        timeout=90.0,
+                    )
+                except Exception:
+                    result = dict(result)
+                    instructions = list(result.get("instructions") or [])
+                    instructions.append(
+                        "Controlled live research was unavailable. Continue only with intake or professional-supplied current official sources; do not substitute another jurisdiction."
+                    )
+                    result["instructions"] = instructions
             return [TextContent(type="text", text=format_jurisdiction_source_pack(result))]
 
         # ── Save Document ───────────────────────────────────────────────────

package/runtime/skill_matcher.py

@@ -11,7 +11,7 @@ import unicodedata
 from collections.abc import Iterable, Mapping, Sequence
 
 
-POLICY_VERSION = "tasksai-trigger-matcher/2.0"
+POLICY_VERSION = "tasksai-trigger-matcher/2.1"
 
 DEFAULT_STOP_WORDS = {
     "a", "an", "and", "are", "as", "at", "be", "by", "can", "create",
@@ -57,11 +57,44 @@ DEFAULT_CONTEXT_WORDS = {
 DEFAULT_THRESHOLDS = {"high": 90, "medium": 45}
 DEFAULT_RESULT_COUNT = 3
 MAXIMUM_RESULT_COUNT = 10
+DEFAULT_RESULT_COUNTS = {"realtor": 5}
+REALTOR_ACTION_WORDS = {
+    "assemble", "build", "create", "develop", "document", "draft",
+    "generate", "make", "prepare", "produce", "write", "writing",
+}
+DEFAULT_TOKEN_ALIASES = {
+    "realtor": {
+        "assemble": "create",
+        "build": "create",
+        "develop": "create",
+        "draft": "create",
+        "dwelling": "property",
+        "generate": "create",
+        "home": "property",
+        "house": "property",
+        "listed": "listing",
+        "listings": "listing",
+        "list": "listing",
+        "make": "create",
+        "prepare": "create",
+        "prepared": "create",
+        "preparing": "create",
+        "preparation": "create",
+        "produce": "create",
+        "residence": "property",
+        "residential": "property",
+        "write": "create",
+        "writing": "create",
+    },
+}
 TRIGGER_EVIDENCE_RANK = {
-    "trigger_exact": 4,
+    "trigger_exact": 5,
+    "trigger_equivalent": 4,
     "trigger_complete": 3,
     "trigger_query_complete": 2,
-    "trigger_partial": 1,
+    "trigger_partial": 2,
+    "trigger_broad": 1,
+    "trigger_context": 1,
 }
 
 
@@ -149,9 +182,95 @@ def _normalize_scoring_tokens(
     value: object,
     stop_words: set[str],
     abbreviations: Mapping[str, object],
+    token_aliases: Mapping[str, str],
 ) -> tuple[str, ...]:
     expanded = _expand_abbreviations(_tokens(value), abbreviations)
-    return tuple(token for token in expanded if token not in stop_words)
+    canonical = tuple(token_aliases.get(token, token) for token in expanded)
+    return tuple(token for token in canonical if token not in stop_words)
+
+
+def _same_token_bag(left: tuple[str, ...], right: tuple[str, ...]) -> bool:
+    return bool(left) and len(left) == len(right) and sorted(left) == sorted(right)
+
+
+def _within_one_edit(left: str, right: str) -> bool:
+    """Return True for one insertion, deletion, substitution, or transposition."""
+    if left == right or abs(len(left) - len(right)) > 1:
+        return False
+    if len(left) == len(right):
+        differences = [index for index, pair in enumerate(zip(left, right)) if pair[0] != pair[1]]
+        if len(differences) == 1:
+            return True
+        return (
+            len(differences) == 2
+            and differences[1] == differences[0] + 1
+            and left[differences[0]] == right[differences[1]]
+            and left[differences[1]] == right[differences[0]]
+        )
+    shorter, longer = (left, right) if len(left) < len(right) else (right, left)
+    short_index = long_index = differences = 0
+    while short_index < len(shorter) and long_index < len(longer):
+        if shorter[short_index] == longer[long_index]:
+            short_index += 1
+            long_index += 1
+            continue
+        differences += 1
+        long_index += 1
+        if differences > 1:
+            return False
+    return True
+
+
+def _build_token_index(
+    skills: Sequence[Mapping[str, object]],
+    triggers: Mapping[str, object],
+    product_id: str,
+    policy: Mapping[str, object],
+) -> tuple[dict[tuple[int, str], set[str]], set[str]]:
+    """Index public discovery tokens by length and first character for bounded typo repair."""
+    stop_words = policy["stop_words"]
+    abbreviations = policy["abbreviations"]
+    token_aliases = policy["token_aliases"]
+    vocabulary = set(token_aliases) | set(token_aliases.values())
+    for skill in skills:
+        for value in (skill.get("name", ""), _category_text(skill)):
+            vocabulary.update(
+                _normalize_scoring_tokens(value, stop_words, abbreviations, token_aliases)
+            )
+        skill_id = str(skill.get("id", ""))
+        for trigger in _trigger_values(triggers, skill_id, product_id):
+            vocabulary.update(
+                _normalize_scoring_tokens(trigger, stop_words, abbreviations, token_aliases)
+            )
+    index: dict[tuple[int, str], set[str]] = {}
+    for token in vocabulary:
+        if len(token) < 5:
+            continue
+        index.setdefault((len(token), token[0]), set()).add(token)
+    return index, vocabulary
+
+
+def _repair_query_tokens(
+    tokens: tuple[str, ...],
+    token_index: Mapping[tuple[int, str], set[str]],
+    vocabulary: set[str],
+) -> tuple[tuple[str, ...], list[str]]:
+    repaired: list[str] = []
+    diagnostics: list[str] = []
+    for token in tokens:
+        if len(token) < 5 or token in vocabulary:
+            repaired.append(token)
+            continue
+        candidates: set[str] = set()
+        for length in range(len(token) - 1, len(token) + 2):
+            candidates.update(token_index.get((length, token[0]), set()))
+        matches = sorted(candidate for candidate in candidates if _within_one_edit(token, candidate))
+        if len(matches) == 1:
+            repaired.append(matches[0])
+            diagnostics.append(f"fuzzy_corrected:{token}->{matches[0]}")
+        else:
+            repaired.append(token)
+    return tuple(repaired), diagnostics
 
 
 def _contains_tokens(container: tuple[str, ...], candidate: tuple[str, ...]) -> bool:
@@ -222,6 +341,8 @@ def _resolve_config(product_id: str, config: Mapping[str, object] | None) -> tup
         for value in supplied_stop_words
         for token in _tokens(value)
     }
+    if _canonical_product_id(product_id) == "realtor":
+        stop_words.difference_update(REALTOR_ACTION_WORDS)
     context_default = DEFAULT_CONTEXT_WORDS.get(_canonical_product_id(product_id), set())
     supplied_context_words = source.get("context_words", context_default)
     if not isinstance(supplied_context_words, Sequence) or isinstance(supplied_context_words, (str, bytes)):
@@ -242,10 +363,13 @@ def _resolve_config(product_id: str, config: Mapping[str, object] | None) -> tup
         diagnostics.append("bundled_thresholds:invalid_order")
         thresholds = dict(DEFAULT_THRESHOLDS)
 
-    default_count = source.get("default_result_count", DEFAULT_RESULT_COUNT)
+    product_default_count = DEFAULT_RESULT_COUNTS.get(
+        _canonical_product_id(product_id), DEFAULT_RESULT_COUNT
+    )
+    default_count = source.get("default_result_count", product_default_count)
     maximum_count = source.get("maximum_result_count", MAXIMUM_RESULT_COUNT)
     if not isinstance(default_count, int) or isinstance(default_count, bool) or default_count < 1:
-        default_count = DEFAULT_RESULT_COUNT
+        default_count = product_default_count
     if not isinstance(maximum_count, int) or isinstance(maximum_count, bool) or maximum_count < 1:
         maximum_count = MAXIMUM_RESULT_COUNT
     maximum_count = min(maximum_count, MAXIMUM_RESULT_COUNT)
@@ -262,6 +386,8 @@ def _resolve_config(product_id: str, config: Mapping[str, object] | None) -> tup
         "default_result_count": default_count,
         "maximum_result_count": maximum_count,
         "abbreviations": configured_abbreviations,
+        "token_aliases": DEFAULT_TOKEN_ALIASES.get(_canonical_product_id(product_id), {}),
+        "broad_matching": _canonical_product_id(product_id) == "realtor",
     }, diagnostics
 
 
@@ -271,8 +397,12 @@ def _score_trigger(
     stop_words: set[str],
     context_words: set[str],
     abbreviations: Mapping[str, object],
+    token_aliases: Mapping[str, str],
+    broad_matching: bool,
 ) -> tuple[int, int, set[str], str]:
-    trigger_tokens = _normalize_scoring_tokens(trigger, stop_words, abbreviations)
+    trigger_tokens = _normalize_scoring_tokens(
+        trigger, stop_words, abbreviations, token_aliases
+    )
     if not trigger_tokens:
         return 0, 0, set(), ""
 
@@ -284,10 +414,14 @@ def _score_trigger(
 
     if query_tokens == trigger_tokens:
         return 120, specificity, matched, "trigger_exact"
+    if broad_matching and _same_token_bag(query_tokens, trigger_tokens):
+        return 110, specificity, matched, "trigger_equivalent"
     if _contains_tokens(query_tokens, trigger_tokens):
         bonus = min(15, max(0, specificity - 1) * 3)
         return 90 + bonus, specificity, matched, "trigger_complete"
     query_specific = query_set - context_words
+    if broad_matching and not query_specific and query_set and query_set <= trigger_set:
+        return 50, specificity, matched, "trigger_context"
     if len(query_specific) >= 2 and _contains_tokens(trigger_tokens, query_tokens):
         return 70, specificity, matched, "trigger_query_complete"
 
@@ -296,6 +430,10 @@ def _score_trigger(
     coverage = len(covered) / len(coverage_tokens)
     if len(covered) >= 2 and coverage >= 0.67:
         return round(40 * coverage), specificity, matched, "trigger_partial"
+    matched_specific_query = matched & (query_set - context_words)
+    matched_context = matched & context_words
+    if broad_matching and matched_specific_query and matched_context:
+        return 35, specificity, matched, "trigger_broad"
     return 0, specificity, set(), ""
 
 
@@ -309,6 +447,8 @@ def _score_skill(
     stop_words = policy["stop_words"]
     context_words = policy["context_words"]
     abbreviations = policy["abbreviations"]
+    token_aliases = policy["token_aliases"]
+    broad_matching = policy["broad_matching"]
     query_set = set(query_tokens)
     specific_query = query_set - context_words
     context_query = query_set & context_words
@@ -317,7 +457,8 @@ def _score_skill(
     strongest_trigger = (0, 0, set(), "", "")
     for trigger in _trigger_values(triggers, skill_id, product_id):
         score, specificity, matched, evidence = _score_trigger(
-            query_tokens, trigger, stop_words, context_words, abbreviations
+            query_tokens, trigger, stop_words, context_words, abbreviations,
+            token_aliases, broad_matching
         )
         candidate = (score, specificity, matched, evidence, normalize_text(trigger))
         candidate_key = (score, specificity, len(matched), normalize_text(trigger))
@@ -335,7 +476,7 @@ def _score_skill(
     matched_tokens = set(trigger_matched)
 
     name_tokens = _normalize_scoring_tokens(
-        skill.get("name", ""), stop_words, abbreviations
+        skill.get("name", ""), stop_words, abbreviations, token_aliases
     )
     name_set = set(name_tokens)
     identity_score = 0
@@ -352,7 +493,9 @@ def _score_skill(
         evidence.append(f"name_context:{token}")
 
     category_set = set(
-        _normalize_scoring_tokens(_category_text(skill), stop_words, abbreviations)
+        _normalize_scoring_tokens(
+            _category_text(skill), stop_words, abbreviations, token_aliases
+        )
     )
     category_score = 0
     for token in sorted(specific_query & category_set):
@@ -365,7 +508,9 @@ def _score_skill(
         evidence.append(f"category_context:{token}")
 
     description_set = set(
-        _normalize_scoring_tokens(skill.get("description", ""), stop_words, abbreviations)
+        _normalize_scoring_tokens(
+            skill.get("description", ""), stop_words, abbreviations, token_aliases
+        )
     )
     description_matches = sorted(specific_query & description_set)
     description_score = len(description_matches)
@@ -457,7 +602,28 @@ def match_skills(
 
     raw_tokens = _tokens(query)
     expanded_tokens = _expand_abbreviations(raw_tokens, configured_abbreviations)
-    query_tokens = tuple(token for token in expanded_tokens if token not in policy["stop_words"])
+    aliased_tokens = tuple(
+        policy["token_aliases"].get(token, token) for token in expanded_tokens
+    )
+    initial_query_tokens = tuple(
+        token for token in aliased_tokens if token not in policy["stop_words"]
+    )
+
+    scoped_skills = [skill for skill in skills if _belongs_to_product(skill, product_id)]
+    if policy["broad_matching"]:
+        token_index, vocabulary = _build_token_index(
+            scoped_skills, triggers, product_id, policy
+        )
+        repaired_tokens, fuzzy_diagnostics = _repair_query_tokens(
+            initial_query_tokens, token_index, vocabulary
+        )
+    else:
+        repaired_tokens, fuzzy_diagnostics = initial_query_tokens, []
+    query_tokens = tuple(
+        policy["token_aliases"].get(token, token) for token in repaired_tokens
+        if policy["token_aliases"].get(token, token) not in policy["stop_words"]
+    )
+    diagnostics.extend(fuzzy_diagnostics)
     query_normalized = " ".join(query_tokens)
 
     requested_count = policy["default_result_count"] if result_count is None else result_count
@@ -465,7 +631,6 @@ def match_skills(
         requested_count = policy["default_result_count"]
     requested_count = max(1, min(requested_count, policy["maximum_result_count"]))
 
-    scoped_skills = [skill for skill in skills if _belongs_to_product(skill, product_id)]
     if len(scoped_skills) != len(skills):
         diagnostics.append("product_mismatches_filtered")