cto-legends · module specification · intelligence · v0.1.6
legends-dataforseo: Zero-Dependency DataForSEO v3 Transport & Offline Evidence Bank
Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.
GitHub Repository (https://github.com/avalonreset/legends-dataforseo) · Handoff: cto-legends handoff legends-dataforseo
legends-dataforseo is a zero-runtime-dependency Python 3.11+ transport library and CLI for DataForSEO API v3 covering Google organic SERP, Google Maps rankings, Google Business Profile (my_business_info), DataForSEO Labs keyword demand, and generic documented v3 endpoints. Designed as the foundational search-data layer for coding agents and downstream modules like legends-geogrid and legends-github, it replaces fragile curl snippets and context-bloating MCP servers with an offline-first execution model: named CLI helpers (serp, maps, business, demand) output exact JSON request previews by default without network calls or credentials.
When live collection is authorized, the transport enforces preflight cost ceilings (--execute, --estimated-cost-usd, --max-cost-usd in CLI; confirm=True in Python), executes a single HTTPS request with zero blind retries on paid POSTs, and preserves the untouched provider envelope including per-task status codes (such as 20100 pending, 40602 in queue, or 40102 empty search result). Built-in research memory commands (legends-dataforseo evidence) package raw responses into content-addressed directories with SHA-256 manifests, enabling fast metadata inventory, dotted-path field extraction, and strict reuse eligibility checks without spending another API credit.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Frontier LLMs have no native access to live, location-coded SERP envelopes, asynchronous Google Maps task queues, or historical search-volume distributions, and pasting multi-megabyte raw DataForSEO JSON responses directly into an agent context window instantly exhausts token budgets. Furthermore, naive agent scripts that wrap HTTP calls in retry loops risk draining account balances when POST requests time out after provider acceptance.
- Single-Submission Transport with Zero Blind Retries: Paid POST requests are never automatically retried or failed over across accounts. If an HTTP timeout or protocol error occurs after submission, ApiError sets request_may_have_completed=True so the caller reconciles task status rather than double-billing the batch.
- Untouched Per-Task Envelope & Status Preservation: When top-level status is 20000, the transport returns the complete provider JSON without converting per-task codes into exceptions. Callers can deterministically separate 40102 (no search results at that coordinate/query) from 40601/40602 (queued/in-progress) and 20000 (completed).
- Zero-Token-Bloat Offline Evidence Navigation: In local benchmarks across 200 packages (~64 KiB each), legends-dataforseo evidence inventory scanned 25 manifest entries in 1.74s while opening zero raw response files, and evidence view --select extracted a 659-byte slice from an 8.4 MB response in 0.066s after full SHA-256 verification.
- Strict Scoped Credential Loading & Sanitized Errors: load_credentials() reads a complete DATAFORSEO_LOGIN/DATAFORSEO_PASSWORD pair from the process environment first, falling back to Windows user environment only if the process pair is completely absent. It never mixes scopes, never reads ad-hoc files, and strips query bodies and secrets from exception tracebacks.
CLI Subcommands & Capability Surface
legends-dataforseo serp | maps | business | demand [args] [--execute --estimated-cost-usd <est> --max-cost-usd <cap>] — Offline-By-Default SERP, Maps, GBP & Keyword Helpers: Constructs validated DataForSEO v3 payloads for Google organic SERP (/serp/google/organic/live/advanced), Google Maps, Google Business Profile (my_business_info by cid, place_id, or keyword), and Labs keyword overview. Previews the exact method, path, and JSON body offline until all three paid execution flags are supplied.legends-dataforseo call <v3-path> [--body-file <file.json>] & legends-dataforseo wait <task-get-path> --execute — Generic v3 Endpoint Dispatch & Bounded Queue Polling: Provides direct GET/POST access to any documented relative v3 path while rejecting absolute URLs, query strings, path traversal, and redirects. For queued Standard tasks, wait (and Python wait_task()) polls supported task_get endpoints with explicit --attempts, --interval, --timeout, and --max-elapsed bounds without resubmitting paid POSTs.legends-dataforseo routes | route <name> | estimate <op> --tasks <n> --depth <d> | docs search | docs read [--offline] — Local Route Registry, Cost Estimator & Cached Endpoint Docs: Inspects the bundled endpoint registry and calculates baseline cost estimates locally without credentials. Searches and reads official DataForSEO v3 documentation with a 24-hour local cache and --offline mode so agents can verify task parameters before constructing payloads.legends-dataforseo view <results.json> [--summary] [--select tasks.0.result.0.items] [--limit <n>] — Reserved File Output & Dotted-Path Response Views: Reserves --output files before HTTP dispatch so existing evidence is never overwritten. Allows agents to inspect saved JSON files offline using --summary (retaining all task IDs, status codes, and costs while omitting heavy result arrays) or --select and --limit with explicit omission counts.legends-dataforseo evidence export | verify | inventory | find | view | reuse — Content-Addressed Research Memory & Reuse Verification: Exports raw task envelopes into immutable packages containing byte-identical response.json, manifest.json, and a SHA-256-bound README.md intake note (note_sha256). Evaluates exact workspace, endpoint, request payload, task status, and --max-age-hours freshness via evidence reuse (exiting 0 for eligible, 2 for ineligible) without network calls.legends-dataforseo doctor [--live] — Offline Readiness & Zero-Charge Live Auth Doctor: Verifies package installation and environment credential presence locally in offline mode. Passing --live performs a single no-charge provider request to confirm authentication status and prints only sanitized status, cost, and credential source metadata.
Raw Frontier LLM vs. legends-dataforseo Execution Matrix
- Default Execution Posture: Raw LLM (Generates ad-hoc curl or Python scripts that fire live paid requests immediately upon execution.) vs. Module (Named CLI commands emit offline JSON previews by default; live POSTs require --execute, --estimated-cost-usd, and --max-cost-usd.) — CostLimitError aborts preflight before credential loading or socket creation if estimated_cost_usd > max_cost_usd.
- Queue & Empty-Result Handling: Raw LLM (Treats HTTP 200 with empty items or pending queue codes as a crash or 'zero market demand', triggering destructive retries.) vs. Module (Preserves per-task status codes (20100, 40601, 40602, 40102) inside the returned envelope; wait_task polls only pending GETs.) — Unit and offline examples verify exact status handling and bounded polling stop reasons.
- Large Response Inspection: Raw LLM (Dumps multi-megabyte SERP or Maps JSON blobs into LLM context or truncates strings mid-object with head/cut.) vs. Module (Saves full untouched JSON to disk and derives labelled views via --summary, --select, and --limit after SHA-256 verification.) — evidence verify cross-checks manifest.json, response.json SHA-256, note_sha256, and per-task metadata while rejecting symlinks.
- Cross-Session Evidence Reuse: Raw LLM (Re-purchases identical keyword or SERP lookups across agent sessions because prior outputs were lost in chat logs.) vs. Module (evidence reuse validates exact workspace, endpoint, request body, completion state, and max-age-hours ceiling offline.) — Returns deterministic exit code 0 when eligible for semantic review or exit code 2 with explicit disqualification reasons.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why does legends-dataforseo have zero third-party runtime dependencies?
- Using only the Python 3.11+ standard library (urllib.request, ssl, json, hashlib, argparse) guarantees clean, deterministic installation across Windows, Linux, and macOS virtual environments without dependency conflicts or background MCP daemon processes.
- How does legends-dataforseo prevent double-charging on asynchronous Google Maps or SERP queues?
- Task submissions (task_post) make exactly one HTTPS request with no automatic retry on timeout, preserving task IDs in the output file. Retrieving results uses bounded GET polling (wait / wait_task) against task_get endpoints, which only re-polls on pending codes (20100, 40601, 40602) and never resubmits a paid POST.
- How does the offline evidence bank protect against corrupted or symlinked files?
- Every exported package stores byte-identical response.json, manifest.json, and README.md with SHA-256 hashes (including note_sha256). During verification and viewing, the tool rejects symlinked files, directory junctions, and linked ancestors, and verifies all file hashes before projecting any --select view.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.