Skill: yangyuwen-bri/patent-retriever-bigquery (version 0.1.2)

--- name: zeelin-patent-retriever description: | Team ZeeLin’s production-grade patent evidence retrieval skill for Google Patents BigQuery. Converts natural-language research intent into auditable multi-round retrieval plans with explicit filters (keywords, country, date, assignee/inventor, IPC/CPC), and outputs validated JSON artifacts for downstream analysis and drafting. Triggers: patent search, prior art, google patents, bigquery patent, 专利检索, 专利查新, 技术情报. homepage: https://github.com/yangyuwen-bri/patent-retriever-bigquery user-invocable: true emoji: 🔎 tags: - patent - patent-search - prior-art - bigquery - google-patents - openclaw metadata: openclaw: homepage: https://github.com/yangyuwen-bri/patent-retriever-bigquery requires: bins: - python3 env: - GOOGLE_APPLICATION_CREDENTIALS - GOOGLE_CLOUD_PROJECT --- # ZeeLin Patent Retriever Team ZeeLin skill for Google Patents retrieval via BigQuery. This skill performs patent retrieval and structured output generation only. It does not provide legal conclusions. ## 30-Second Quickstart Card Purpose: - Fetch, deduplicate, and structure patent evidence from Google Patents BigQuery for downstream analysis. Required env: - `GOOGLE_APPLICATION_CREDENTIALS` - `GOOGLE_CLOUD_PROJECT` Run this: ```bash python3 -m pip install -r requirements.txt RUN_ID="quick_$(date +%Y%m%d_%H%M%S)"; RUN_DIR="results/${RUN_ID}"; mkdir -p "$RUN_DIR" python3 scripts/patent_search.py --keywords "ai sentiment analysis" --limit 80 --output "$RUN_DIR/seed_raw.json" python3 scripts/build_query_plan.py --topic "Public Opinion + AI" --keywords "public opinion ai sentiment" --task-id "$RUN_ID" --seed-raw "$RUN_DIR/seed_raw.json" --concept-output "$RUN_DIR/concept_scan.json" --plan-output "$RUN_DIR/query_plan.json" python3 scripts/patent_search_plan.py --plan "$RUN_DIR/query_plan.json" --output-raw "$RUN_DIR/retriever_raw.json" --output-retriever "$RUN_DIR/retriever_result.json" --min-results 20 ``` Expected outputs: - `$RUN_DIR/concept_scan.json` - `$RUN_DIR/query_plan.json` - `$RUN_DIR/retriever_raw.json` - `$RUN_DIR/retriever_result.json` If it fails: - Missing env vars: configure Google credentials first. - Too few results: keep filters and increase limits/expansion rounds before relaxing constraints. ## 1. Execution Rules 1. Use the three-stage flow by default: `seed -> build_plan -> execute_plan`. 2. Default minimum result count is `20` unless the user explicitly requests another value. 3. If the user specifies hard constraints (year, country, assignee, inventor, IPC/CPC), they must be applied in `query_plan.json` (`filters`) before execution. 4. Before execution, echo planned filters. After execution, echo effective filters, result size, and output file paths. ## 2. Pre-Run Checks Required environment variables: - `GOOGLE_APPLICATION_CREDENTIALS` - `GOOGLE_CLOUD_PROJECT` Install dependencies: ```bash python3 -m pip install -r requirements.txt ``` Optional environment check: ```bash python3 - <<'PY' import os required = ["GOOGLE_APPLICATION_CREDENTIALS", "GOOGLE_CLOUD_PROJECT"] missing = [k for k in required if not os.getenv(k)] print({"ok": not missing, "missing": missing}) PY ``` ## 3. Capability Boundary and Parameter Sources ### 3.1 Supported filter dimensions - Text: `keywords_all` / `keywords_any` / `keywords_anchor_any` / `keywords_not` - Taxonomy: `ipc_prefix_any` / `cpc_prefix_any` - Entities: `assignee_any` / `inventor_any` - Geography: `country_in` - Date ranges: `pub_date_from` / `pub_date_to` / `filing_date_from` / `filing_date_to` Field source: `query_plan.json` (schema: `schemas/query_plan.schema.json`). ### 3.2 Default behavior for missing inputs - `min_results`: default `20` - Country unspecified: default `US,CN,WO,EP,JP,KR` - Date range unspecified: default `years_back=8` - Keywords missing: ask for clarification and do not run ### 3.3 Year-to-date mapping rules - Single year (e.g. `2021`) => `from=20210101`, `to=20211231` - Year range (e.g. `2021-2023`) => `from=20210101`, `to=20231231` - Relative window (e.g. “last N years”) => use `--years-back N` ## 4. Standard Flow (Command Templates) Create a run directory first: ```bash RUN_ID="run_$(date +%Y%m%d_%H%M%S)" RUN_DIR="results/${RUN_ID}" mkdir -p "$RUN_DIR" ``` ### Step 1: Seed retrieval ```bash python3 scripts/patent_search.py \ --keywords "<keywords>" \ --limit 80 \ --output "$RUN_DIR/seed_raw.json" ``` ### Step 2: Build query plan ```bash python3 scripts/build_query_plan.py \ --topic "<topic>" \ --keywords "<keywords>" \ --task-id "$RUN_ID" \ --years-back 8 \ --country-in "US,CN,WO,EP,JP,KR" \ --seed-raw "$RUN_DIR/seed_raw.json" \ --concept-output "$RUN_DIR/concept_scan.json" \ --plan-output "$RUN_DIR/query_plan.json" ``` ### Step 3: Apply explicit user constraints (critical) When the user explicitly requests country/year/assignee filters, patch `query_plan.json` before execution. ```bash python3 - <<'PY' import json import os from pathlib import Path plan_path = Path(os.environ["RUN_DIR"]) / "query_plan.json" plan = json.loads(plan_path.read_text(encoding="utf-8")) # Example override: 2021-2023 + US + keyword constraints for r in plan.get("query_rounds", []): f = r.setdefault("filters", {}) f["country_in"] = ["US"] f["pub_date_from"] = 20210101 f["pub_date_to"] = 20231231 f.setdefault("keywords_any", []) f["keywords_any"] = list(dict.fromkeys(f["keywords_any"] + ["sentiment", "public opinion", "risk"])) plan_path.write_text(json.dumps(plan, ensure_ascii=False, indent=2), encoding="utf-8") print({"updated": str(plan_path)}) PY ``` ### Step 4: Execute planned retrieval ```bash python3 scripts/patent_search_plan.py \ --plan "$RUN_DIR/query_plan.json" \ --output-raw "$RUN_DIR/retriever_raw.json" \ --output-retriever "$RUN_DIR/retriever_result.json" \ --min-results 20 ``` ### Step 5: Validate outputs ```bash python3 scripts/schema_check.py --input "$RUN_DIR/concept_scan.json" --schema schemas/concept_scan.schema.json python3 scripts/schema_check.py --input "$RUN_DIR/query_plan.json" --schema schemas/query_plan.schema.json python3 scripts/schema_check.py --input "$RUN_DIR/retriever_result.json" --schema schemas/retriever_result.schema.json ``` ## 5. Natural Language to Parameter Mapping Examples Example A: - User input: `Find US patents on AI public-opinion early warning from 2021 to 2023, at least 30 results` - Mapping: - `topic="AI public opinion early warning"` - `keywords="ai public opinion early warning sentiment"` - Plan override: `country_in=["US"]`, `pub_date_from=20210101`, `pub_date_to=20231231` - Execution arg: `--min-results 30` Example B: - User input: `Search multimodal emotion recognition patents in CN/JP/KR over the last 5 years, focus on Tencent and ByteDance` - Mapping: - `--years-back 5` - `country_in=["CN","JP","KR"]` - `assignee_any=["Tencent","ByteDance"]` ## 6. Post-Execution Response Template (required) ```text Retrieval completed. Effective filters: - Countries: ... - Publication date range: ... - Filing date range: ... - Keywords (any/all/not): ... - Assignee/Inventor filters: ... Results: - Patent count: ... - Country distribution: ... - Latest publication date: ... Files: - concept_scan: ... - query_plan: ... - retriever_raw: ... - retriever_result: ... ``` ## 7. Common Failures and Recovery - Missing environment variables: instruct user to configure Google credentials first. - Insufficient retrieval volume: 1. Keep constraints, increase per-round limits. 2. Increase expansion rounds. 3. If still insufficient, ask whether to relax country/date constraints. - Cost risk: prioritize narrower date windows and country scopes before broad scans. ## 8. Output Contract Required output files: - `concept_scan.json` - `query_plan.json` - `retriever_raw.json` - `retriever_result.json` `retriever_result.json` minimum requirements: - `patents` count `>= min_results` (default 20) - each item includes `publication_number` and `title` ## 9. References - Methodology: `references/methodology.md` - Quick examples: `examples/quickstart.md`

path: requirements.txt
content: python-dotenv>=1.0.0
google-cloud-bigquery>=3.20.0
jsonschema>=4.20.0


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)