⟠ GEO-Scope
Empirical AI Answer Visibility Measurement Framework
An open-source framework for empirical measurement of AI answer visibility, entity mentions, recommendations, and citations across generative AI systems.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
An open-source framework for empirical measurement of AI answer visibility, entity mentions, recommendations, and citations across generative AI systems.
Open framework for empirical AI visibility benchmarks, multi-model provider observation, and reproducible GEO research.
🏆 Landmark Benchmark (Iran & Türkiye) • Introduction • What It Measures • Scientific Foundation • Benchmarks • Reproducibility • Research • Quickstart • MCP
[!IMPORTANT]
📊 Exploratory Regional Commercial AI Visibility Pilot
This pilot benchmark marks an exploratory empirical baseline evaluating commercial AI search visibility, entity recommendations, and web citation patterns across Iran (
fa-IR) and Türkiye (tr-TR). Conducted with zero synthetic fabrication, 100% real-time search-grounded completions, and cryptographic auditability, it establishes an evidence-backed baseline for Generative Engine Optimization (GEO) research in regional markets.
Explore Benchmark Dataset & Specs • Full Results (English) • گزارش نتایج (فارسی) • Sonuç Raporu (Türkçe) • Nəticələr (Azərbaycan) • النتائج الكاملة (العربية)
fa-IR) Commercial Market (72 completions)tr-TR) Commercial Market (72 completions)Scientific Integrity Note: Stradiji received 0 brand mentions; 60 false-positive token matches with the Turkish word 'strateji' were filtered by GEO-Scope's entity disambiguation engine.
sonar-pro): 1,003 citations (20.90 citations/query, 7.94s avg latency)gemini-2.5-flash): 944 citations (19.67 citations/query, 17.85s avg latency)gpt-4o): 344 citations (7.17 citations/query, 10.42s avg latency)agencies.semrush.com #1 with 22 citations, edvido.com #2 with 16 citations, pr.net.tr #3 with 16 citations).iranweblife.com #1 with 21 citations, miladjalayi.com #2 with 14 citations) and digital PR platforms (triboon.net #5 with 12 citations).GEO-Scope پاسخهای یک یا چند موتور هوش مصنوعی را بررسی میکند و پنج چیز را جداگانه گزارش میدهد: آیا نام شما آمده، آیا پیشنهاد شده، آیا لینک یا citation داده شده، آیا مطلبی به شما نسبت داده شده و آیا در فهرست رتبه گرفتهاید.
خود موتور بهتنهایی کلید API ندارد و چیزی را جعل نمیکند. برای یک تست بدون هزینه و بدون اینترنت از حالت simulation یا replay استفاده کنید. برای live باید خودتان دسترسی و کلید ارائهدهندهی موردنظر را تنظیم کنید؛ Hugging Face، ZeroGPU و «LLM رایگان نامحدود» جزو نیازمندیهای این بسته نیستند.
pip install geo-scope
geo-scope demo
این دستور یک SIMULATION FIXTURE میسازد؛ یعنی برای یادگیری و بررسی فرمت خروجی است و به مدل زنده وصل نمیشود. بنابراین عددهای آن را گزارش واقعی بازار یا رتبهی برند ندانید.
simulation: اجرای آزمایشی قطعی و بدون تماس با مدل.live: اجرای واقعی با provider و هزینه/کلید همان provider.replay: تحلیل دوبارهی پاسخهای ذخیرهشده، کاملاً آفلاین.citation: لینکی که موتور پاسخ بهعنوان منبع نشان داده؛ با «ذکر نام» یکی نیست.دموی عمومی Space عمداً بدون کلید و بدون GPU کار میکند و خروجی آن fixture قطعی است. برای یک اندازهگیری زنده با مدل متنباز، کلید حساب خودتان را فقط در محیط محلی بگذارید:
pip install geo-scope
export HF_TOKEN="hf_..."
# در صورت نیاز مدل قابلدسترسی حساب/ارائهدهنده را انتخاب کنید
export HF_MODEL="Qwen/Qwen2.5-7B-Instruct"
geo-scope measure \
--entities examples/public_demo/brands.json \
--prompts examples/public_demo/prompts/observed.jsonl \
--providers huggingface_inference \
--mode live \
--out-dir output/hf-live
hf، huggingface و huggingface_inference نامهای قابلاستفادهاند. این
provider پاسخ مدل را میسنجد، اما web search یا citation واقعی به آن اضافه
نمیکند؛ بنابراین citationهای خروجی را فقط وقتی گزارش کنید که خود مدل واقعاً
لینک داده باشد. کلید را در README، فایل Space، issue، commit یا لاگ قرار
ندهید. اعتبار رایگان Hugging Face محدود و وابسته به سیاست فعلی حساب است؛
«رایگان نامحدود» وعدهی فنی قابلاتکایی نیست. برای استفادهی بدون هزینهی
ابری، از simulation/replay یا یک مدل محلی با Ollama استفاده کنید.
اگر هدف فقط یادگیری است، از demo شروع کنید. اگر هدف اندازهگیری واقعی visibility است، ابتدا یک فایل entity و یک فایل prompt آماده کنید، provider را تنظیم کنید و بعد live را اجرا کنید. بدون پاسخ واقعی provider، GEO-Scope ادعای visibility نمیکند. راهنمای فارسی برای مثالهای تیمی آماده است.
Generative AI systems and search-grounded answer engines are rapidly becoming the primary discovery layer for users seeking products, vendors, services, and factual insights.
GEO-Scope is an evidence-first, open-source measurement framework designed to empirically quantify and preserve auditable evidence of how generative AI systems surface entities. It records, normalizes, and analyzes observable AI completions under documented, neutral prompt sets without relying on speculative ranking algorithms or ungrounded claims.
GEO-Scope enforces a strict taxonomic separation between four independent visibility dimensions:
┌─────────────────────────────────────────────────────────────────────────┐
│ AI RESPONSE VISIBILITY MATRIX │
├───────────────────┬─────────────────────────────────────────────────────┤
│ Mention │ Did the entity appear anywhere in the completion? │
│ Recommendation │ Was the entity explicitly endorsed or recommended? │
│ Citation │ Was a source URL or grounding domain link provided? │
│ Attribution │ Was specific data/claim textually credited to it? │
│ Rank │ Extracted ONLY when a valid ordered list exists. │
└───────────────────┴─────────────────────────────────────────────────────┘
mentioned: true/false):
recommended: true/false):
mentioned != recommended.cited: true/false):
attributed: true/false):
rank: 1..N | null):
null to prevent artificial ranking bias.To maintain scientific integrity, GEO-Scope clearly outlines its epistemic boundaries:
GEO-Scope operates as a modular, six-stage evidence pipeline:
┌─────────────────────────────────────────────────────────────┐
│ Provider Layer │
│ ┌──────────────────────────┐ ┌────────────────────────┐ │
│ │ Search Answer Engines │ │ Parametric Base LLMs │ │
│ │ (Perplexity, Gemini...) │ │ (OpenAI, Claude...) │ │
│ └──────────────────────────┘ └────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Measurement Engine │
│ (Prompt Provenance · Zero Silent Fallback · Runs) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Raw Response Storage │
│ (Unparsed API Payloads · Latency · Token Usage) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Observation Parser │
│ (Multi-Lingual Normalizer · Homonyms · Citations) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Metrics Calculation │
│ (OMR · Rec Share · Citation Rate · Honest Denominators) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Reports + Replayable Bundle │
│ (JSONL Bundles · SHA-256 Checksums · Markdown Summaries) │
└─────────────────────────────────────────────────────────────┘
GEO-Scope provides three mutually exclusive execution modes:
demo (Simulation Fixture)simulated_*) and a clear simulation banner.measure (Live Empirical Execution)raw_responses.jsonl with exact model governance metadata (requested_provider, actual_provider, search_grounded).replay (Deterministic Offline Replay)raw_responses.jsonl.GEO-Scope does not claim universal AI visibility truth. It measures empirical observations under declared, reproducible measurement configurations.
[!IMPORTANT] Fundamental Measurement Axiom
"AI visibility is an observation under a declared measurement system, not a universal ground-truth ranking."
docs/SCIENTIFIC_MEASUREMENT_GATE.mddocs/METHODOLOGY.mdschemas/v0.3/manifest.schema.jsonexamples/public_demo/manifest.jsondocs/index.mdentity_mentioned in text, target_domain_cited (root domain), target_url_cited (deep link), and third_party_source_cited (external authority/review links). Mention and citation are never treated as equivalent.experimental.comparable: true only when prompt universe, market/language, provider/model family, measurement definitions, and observation windows match.response_hash_sha256), extracted entities, citations, and execution configuration hash.GEO-Scope maintains immutable, peer-review-ready benchmark releases under benchmark/releases/ (see the documentation index):
REPRODUCED_DIRECTIONALLY). Intermediate query fan-out tracking is preserved as an experimental diagnostic layer and explicitly excluded from composite visibility scores to avoid causal overreach.Every release bundle contains:
manifest.json: Dataset metadata, provider matrix, and schema version (measurement_contract_version: "1.0").prompts.jsonl: Neutral, categorized prompts.raw_responses.jsonl: Verbatim API completion payloads.observations.jsonl: Granular extracted observation records.metrics.json: Aggregated metrics with explicit failure denominators.checksums.sha256: SHA-256 hashes of all artifacts.Verify that dataset files have not been modified or corrupted:
geo-scope benchmark verify --dataset benchmark/releases/global-ai-answers-2026.2
Replay metrics directly from preserved raw responses without executing live API calls:
geo-scope replay \
--bundle benchmark/releases/global-ai-answers-2026.2 \
--out-dir output/replay_2026_2
Evaluate the deterministic multi-lingual parser against human-labeled ground truth:
geo-scope parser evaluate --golden-set benchmark/golden_sets/v1
Golden Set Benchmark Results (v1, 220 examples across 5 languages):
99.75% (Precision: 99.51%, Recall: 100.00%)100.00% (Precision: 100.00%, Recall: 100.00%)100.00% (Precision: 100.00%, Recall: 100.00%)91.56% (Precision: 100.00%, Recall: 84.44%)96.97%100.00%docs/SCIENTIFIC_MEASUREMENT_GATE.mddocs/METHODOLOGY.mddocs/index.mddocs/METHODOLOGY.mddocs/research/global-ai-answers-2026.2/global-ai-answers-paper.mddocs/REALITY_AUDIT.mddocs/METHODOLOGY_CROSSWALK.mddocs/benchmark-methodology.mddocs/EVIDENCE_MAP.mddocs/MATHEMATICAL_MODEL.mddocs/API_INTEGRATION.mddocs/SCIENTIFIC_MEASUREMENT_GATE.md# Clone the repository
git clone https://github.com/tmolavi/geo-scope.git
cd geo-scope
# Install package in editable mode
pip install -e .
The stable package is available at PyPI. Future releases are published from GitHub Actions through Trusted Publishing; no PyPI token is stored in the repository.
To publish a new version:
pyproject.toml.main.The workflow is .github/workflows/publish.yml
and uses the pypi GitHub environment for tmolavi/geo-scope. The PyPI-side
publisher must remain mapped to Owner tmolavi, Repository geo-scope,
Workflow publish.yml, Environment pypi.
Do not put a PyPI API token in GitHub secrets or commit it to this repository.
# 1. Run local simulation fixture demo
geo-scope demo
# 2. Execute live empirical measurement (requires API credentials)
geo-scope measure \
--entities entities/iran-seo-agencies.json \
--prompts examples/research_run/prompts.jsonl \
--mode live \
--providers perplexity_sonar,gemini_grounding \
--out-dir output/live_run_01
# 3. Deterministic offline replay
geo-scope replay \
--bundle output/live_run_01 \
--out-dir output/replay_run_01
# 4. Launch interactive local research dashboard
geo-scope serve --host 127.0.0.1 --port 8000
GEO-Scope includes a native MCP Server (stdio), enabling AI coding assistants and agents (Claude Desktop, Cursor, Antigravity) to query visibility benchmarks and inspect entity evidence chains directly:
{
"mcpServers": {
"geo-scope": {
"command": "/absolute/path/to/geo-scope/.venv/bin/geo-scope",
"args": ["mcp"]
}
}
}
See the Client Integrations Guide for full configuration details.
Developed by Taqi Molavi (Senior SEO Strategist & GEO Systems Architect).
Part of the Molavi GEO Pyramid research initiative.
@software{molavi2026geoscope,
author = {Molavi, Taqi},
title = {GEO-Scope: Empirical AI Answer Visibility Measurement Framework},
year = {2026},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/tmolavi/geo-scope}},
note = {Personal Homepage: https://molavi.pro/}
}
This project is licensed under the MIT License — Copyright (c) 2026 تقی مولوی (Taqi Molavi).
Open framework for empirical AI visibility benchmarks, multi-model provider observation, and reproducible GEO research.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Geo Scope 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 Open framework for empirical AI visibility benchmarks, multi-model provider observation, and reproducible GEO research.