answerpath-geo 0.1.0__py3-none-any.whl

answerpath_geo/__init__.py

@@ -0,0 +1,2 @@
+from .core import Question, extract_records, mine
+__all__ = ["Question", "extract_records", "mine"]

answerpath_geo/cli.py

@@ -0,0 +1,16 @@
+import argparse, sys
+from .core import extract_records, mine, write_outputs
+
+def main(argv=None):
+    argv=sys.argv[1:] if argv is None else argv
+    if argv and argv[0]=="mcp":
+        from .mcp import stdio; stdio(); return
+    if argv and argv[0] in {"serve-mcp","mcp-http"}:
+        from .mcp import http
+        p=argparse.ArgumentParser(prog="answerpath serve-mcp"); p.add_argument("--host",default="127.0.0.1"); p.add_argument("--port",type=int,default=8787); a=p.parse_args(argv[1:]); http(a.host,a.port); return
+    p=argparse.ArgumentParser(prog="answerpath", description="Mine user questions for GEO/AEO")
+    p.add_argument("topic", help="service, business, website or keyword"); p.add_argument("--input", action="append", default=[], help="owned JSON/JSONL/CSV export or directory; repeatable"); p.add_argument("--out", default="answerpath-output"); p.add_argument("--no-generated", action="store_true", help="only keep observed questions")
+    a=p.parse_args(argv); rows=[]
+    for x in a.input: rows.extend(extract_records(x))
+    qs=mine(a.topic, rows, not a.no_generated); out=write_outputs(qs,a.out)
+    print(f"Wrote {len(qs)} questions to {out} (observed={sum(q.evidence.startswith('observed') for q in qs)})")

answerpath_geo/core.py

@@ -0,0 +1,120 @@
+"""Question mining engine: deterministic, local-first, and explicit about evidence."""
+from __future__ import annotations
+import csv, json, re, zipfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from difflib import SequenceMatcher
+
+@dataclass
+class Question:
+    text: str
+    source: str
+    evidence: str  # observed | generated
+    intent: str
+    stage: str
+    frequency: int = 1
+    cluster: int = -1
+
+INTENTS = {
+    "learn": ["what", "چیست", "چیه", "چطور", "how", "guide"],
+    "compare": ["compare", "مقایسه", "بهتر", "vs", "versus", "فرق"],
+    "buy": ["price", "قیمت", "خرید", "buy", "cost", "پکیج", "هزینه"],
+    "solve": ["مناسب", "حل", "مشکل", "نرم افزار", "service", "خدمت", "حل کردن"],
+    "trust": ["review", "نظرات", "اعتماد", "قابل اعتماد", "تجربه", "review"],
+}
+
+def _text(value) -> str:
+    if isinstance(value, str): return re.sub(r"\s+", " ", value).strip()
+    if isinstance(value, list): return _text(" ".join(_text(x.get("text", "") if isinstance(x, dict) else x) for x in value))
+    if isinstance(value, dict): return _text(value.get("content", value.get("text", "")))
+    return ""
+
+def extract_records(path: str | Path) -> list[tuple[str, str]]:
+    """Read owned exports/logs; never accesses provider accounts or remote chats."""
+    p = Path(path); rows=[]
+    files=[]
+    if p.suffix.lower()==".zip":
+        with zipfile.ZipFile(p) as z:
+            for n in z.namelist():
+                if n.lower().endswith((".json", ".jsonl", ".csv")): rows.extend(_read_bytes(n, z.read(n), str(p)))
+        return rows
+    if p.is_dir(): files=[x for x in p.rglob("*") if x.suffix.lower() in {".json", ".jsonl", ".csv"}]
+    else: files=[p]
+    for f in files: rows.extend(_read_bytes(str(f), f.read_bytes(), str(f)))
+    return rows
+
+def _read_bytes(name, data, source):
+    try: obj=json.loads(data)
+    except Exception:
+        try: obj=[json.loads(x) for x in data.decode().splitlines() if x.strip()]
+        except Exception: obj=None
+    if obj is not None: return _walk(obj, source)
+    try:
+        out=[]
+        for row in csv.DictReader(data.decode().splitlines()):
+            if str(row.get("role", row.get("speaker", ""))).lower() in {"user","human","customer"}: out.append((_text(row.get("content", row.get("text", ""))), source))
+        return out
+    except Exception: return []
+
+def _walk(obj, source):
+    out=[]
+    if isinstance(obj, dict):
+        role=str(obj.get("role", obj.get("author", obj.get("speaker", "")))).lower()
+        if role in {"user","human","customer"}:
+            t=_text(obj.get("content", obj.get("text", obj.get("message", ""))))
+            if t: out.append((t, source))
+        for v in obj.values(): out.extend(_walk(v, source))
+    elif isinstance(obj, list):
+        for v in obj: out.extend(_walk(v, source))
+    return out
+
+def classify(text):
+    low=text.lower()
+    # Commercial and comparison signals should win over broad "how/what"
+    # markers (for example, "How much does ... cost?" is a buying question).
+    for intent in ("buy", "compare", "trust", "solve", "learn"):
+        words = INTENTS[intent]
+        if any(w in low for w in words): return intent
+    return "discover"
+
+def stage(intent): return {"learn":"awareness","compare":"consideration","trust":"consideration","buy":"decision","solve":"decision"}.get(intent,"awareness")
+
+def generated_prompts(topic):
+    return [
+      f"What is the best {topic} for a small business?",
+      f"How do I choose a reliable {topic} provider?",
+      f"What should I compare before buying {topic}?",
+      f"How much does {topic} cost and what is included?",
+      f"Which {topic} is suitable for my needs?",
+      f"What are the common problems with {topic} and how are they solved?",
+      f"Are there trustworthy reviews or examples for {topic}?",
+      f"Compare the leading {topic} options for quality and price.",
+    ]
+
+def mine(topic, inputs=(), include_generated=True, threshold=.88):
+    qs=[]
+    for text, source in inputs:
+        text=_text(text)
+        if len(text)<4 or len(text)>1000: continue
+        intent=classify(text); qs.append(Question(text, source, "observed", intent, stage(intent)))
+    if include_generated:
+        for text in generated_prompts(topic):
+            intent=classify(text); qs.append(Question(text, "answerpath:template", "generated", intent, stage(intent)))
+    groups=[]
+    for q in qs:
+        match=None
+        for existing in groups:
+            if SequenceMatcher(None, q.text.lower(), existing.text.lower()).ratio()>=threshold:
+                match=existing; break
+        if match: match.frequency+=1; match.source += ";"+q.source; match.evidence = "observed+generated" if match.evidence!=q.evidence else match.evidence
+        else: groups.append(q)
+    for i,q in enumerate(groups): q.cluster=i
+    return groups
+
+def write_outputs(questions, out):
+    out=Path(out); out.mkdir(parents=True, exist_ok=True)
+    data=[asdict(q) for q in questions]
+    (out/"questions.json").write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    with (out/"questions.csv").open("w", newline="", encoding="utf-8") as f:
+        w=csv.DictWriter(f, fieldnames=data[0].keys() if data else ["text"]); w.writeheader(); w.writerows(data)
+    return out

answerpath_geo/mcp.py

@@ -0,0 +1,37 @@
+"""Minimal dependency-free MCP-compatible JSON-RPC transports."""
+import json, sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from .core import mine
+
+TOOLS = [{"name":"discover_questions","description":"Extract and classify observed questions, then optionally add labeled GEO/AEO hypotheses.","inputSchema":{"type":"object","properties":{"topic":{"type":"string"},"inputs":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"}}}},"include_generated":{"type":"boolean","default":True}},"required":["topic"]}}]
+
+def call_tool(name, args):
+    if name != "discover_questions": raise ValueError(f"unknown tool: {name}")
+    rows=[(x.get("text",""), x.get("source","mcp")) for x in args.get("inputs",[]) if isinstance(x,dict)]
+    result=[q.__dict__ for q in mine(args["topic"], rows, args.get("include_generated",True))]
+    return {"content":[{"type":"text","text":json.dumps(result,ensure_ascii=False)}],"structuredContent":{"questions":result}}
+
+def handle(req):
+    method=req.get("method"); rid=req.get("id")
+    if method=="initialize": result={"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"answerpath-geo","version":"0.1.0"}}
+    elif method=="tools/list": result={"tools":TOOLS}
+    elif method=="tools/call": result=call_tool(req.get("params",{}).get("name"),req.get("params",{}).get("arguments",{}))
+    else: return {"jsonrpc":"2.0","id":rid,"error":{"code":-32601,"message":"Method not found"}}
+    return {"jsonrpc":"2.0","id":rid,"result":result}
+
+def stdio():
+    for line in sys.stdin:
+        try: print(json.dumps(handle(json.loads(line)),ensure_ascii=False),flush=True)
+        except Exception as e: print(json.dumps({"jsonrpc":"2.0","id":None,"error":{"code":-32000,"message":str(e)}},ensure_ascii=False),flush=True)
+
+class Handler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        if self.path.rstrip("/") != "/mcp": self.send_error(404); return
+        n=int(self.headers.get("Content-Length","0"));
+        try: body=json.loads(self.rfile.read(n)); out=handle(body); raw=json.dumps(out,ensure_ascii=False).encode()
+        except Exception as e: raw=json.dumps({"jsonrpc":"2.0","id":None,"error":{"code":-32000,"message":str(e)}},ensure_ascii=False).encode()
+        self.send_response(200); self.send_header("Content-Type","application/json"); self.send_header("Content-Length",str(len(raw))); self.end_headers(); self.wfile.write(raw)
+    def log_message(self,*args): pass
+
+def http(host="127.0.0.1", port=8787):
+    ThreadingHTTPServer((host,port),Handler).serve_forever()

answerpath_geo-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: answerpath-geo
+Version: 0.1.0
+Summary: Privacy-first user question mining for GEO and AEO
+Author: Taqi Molavi
+License: MIT
+Project-URL: Homepage, https://molavi.pro
+Project-URL: Repository, https://github.com/tmolavi/answerpath-geo
+Project-URL: Documentation, https://github.com/tmolavi/answerpath-geo#readme
+Project-URL: Issues, https://github.com/tmolavi/answerpath-geo/issues
+Keywords: geo,aeo,seo,answer-engine-optimization,prompt-mining,user-intent,question-mining
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AnswerPath GEO — Discover the Questions People Ask AI Before They Find Your Business
+
+**AnswerPath GEO** is a privacy-first, open-source **SEO, GEO and AEO question mining engine**. Give it a business, service, website topic or keyword and it builds a transparent question map showing what people may ask an AI assistant before choosing a provider.
+
+It separates **observed questions** extracted from exports and application logs from **generated research prompts**. This distinction matters: generated prompts are hypotheses, not evidence of what people actually asked.
+
+[Installation](#installation) · [Quick start](#quick-start) · [Inputs](#supported-inputs) · [Outputs](#outputs) · [GEO/AEO method](#geo-and-aeo-method) · [Privacy](#privacy-and-data-boundaries) · [Integrations](#integrations)
+
+**MCP clients:** [Codex, Antigravity, Claude, Cursor and Cloud setup](#mcp-setup)
+
+## Why AnswerPath GEO?
+
+Traditional keyword tools show phrases typed into search engines. AI assistants receive longer, conversational questions: “Which agency is reliable for…?”, “What should I compare…?”, and “Is this service worth the price?”. AnswerPath turns the questions you already own into a usable **answer-path map** for content, FAQ, schema and AI visibility research.
+
+It is designed for marketers, publishers, agencies and product teams who need to:
+
+- discover and normalize user questions from ChatGPT, Claude, Codex, Antigravity, Cursor and chatbot exports;
+- group questions by intent and decision stage;
+- identify recurring questions without silently inventing demand;
+- create an auditable prompt bank for GEO/AEO experiments;
+- keep private conversation data on the operator’s machine.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+git clone https://github.com/tmolavi/answerpath-geo.git
+cd answerpath-geo
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## Quick start
+
+Create a prompt map for a service or keyword:
+
+```bash
+answerpath "طراحی سایت فروشگاهی"
+```
+
+The command writes `answerpath-output/questions.json` and `questions.csv`.
+
+Analyze owned conversation data and add generated discovery prompts:
+
+```bash
+answerpath "مشاوره سئو پزشکی" \\
+  --input ~/Downloads/chatgpt-export.zip \\
+  --input ./support-chat.json \\
+  --out ./research/seo-medical
+```
+
+Keep only questions actually found in your supplied data:
+
+```bash
+answerpath "سرویس حسابداری" --input ./logs --no-generated
+```
+
+## Supported inputs
+
+AnswerPath reads local JSON, JSONL, CSV, directories and ZIP archives. It recognizes common `role=user|human|customer` fields and nested ChatGPT/Claude export structures. It is compatible in principle with exports produced by tools such as [openai_export_parser](https://github.com/temnoon/openai_export_parser), [llm-export-analytics](https://github.com/noah-chelednik/llm-export-analytics), and the local multi-client history model used by [ContextBridgeAI](https://github.com/T-Gojo/ContextBridgeAi).
+
+It does not log in to ChatGPT, Claude, Google, or any other account, scrape other users, or obtain API keys.
+
+## Outputs
+
+Each normalized question contains:
+
+| Field | Meaning |
+|---|---|
+| `text` | Question text as extracted or generated |
+| `evidence` | `observed`, `generated`, or `observed+generated` |
+| `source` | Input file or generation rule |
+| `intent` | `learn`, `compare`, `buy`, `solve`, `trust`, or `discover` |
+| `stage` | Awareness, consideration or decision |
+| `frequency` | Number of similar records merged |
+| `cluster` | Stable output cluster identifier |
+
+Frequency is meaningful only for observed records from a defined dataset. Template prompts are clearly labeled and must not be reported as customer demand.
+
+## GEO and AEO method
+
+AnswerPath supports a defensible workflow:
+
+1. **Collect** owned exports, support logs or application traces.
+2. **Extract** user turns and preserve their source path.
+3. **Normalize** whitespace and common message formats.
+4. **Classify** intent and decision stage with inspectable rules.
+5. **Deduplicate** near-identical questions while retaining frequency.
+6. **Expand** with clearly labeled prompt hypotheses when requested.
+7. **Publish answers**: create concise answer-first pages, FAQ sections, comparison tables and structured data based on recurring observed questions.
+8. **Measure** those prompts in a separate GEO benchmark; never mix hypotheses with measured demand.
+
+The engine does not claim that a page will rank in Google or be cited by an AI system. Those are outcomes to test with your own content and provider evidence.
+
+## Integrations
+
+- **ChatGPT / Claude exports:** pass the downloaded ZIP or extracted JSON to `--input`.
+- **Codex, Antigravity, Cursor and other AI IDEs:** export or copy the local session data first; use a read-only copy as input.
+- **FAQ workflows:** feed `questions.json` into [FAQ Extraction Pipeline](https://github.com/emfrg/faq-extraction-pipeline) for richer issue extraction, embeddings and FAQ synthesis.
+- **GEO prompt discovery:** compare observed questions with generated candidates from projects such as [auto-geo](https://github.com/shadowresearch/auto-geo), keeping the evidence labels separate.
+
+## 🏆 Evidence & Benchmark Contribution
+
+AnswerPath GEO generated the **Question Discovery & Intent Stratification Layer** used in the official [GEO, SEO & Digital Marketing Agency Iran 2026 Benchmark](https://github.com/tmolavi/geo-scope/tree/main/benchmarks/geo-seo-digital-agency-iran-2026.1):
+
+- **Verified Query Dataset**: [`examples/sample_queries.json`](examples/sample_queries.json)
+- **Standalone Offline Demo**: [`examples/public_demo/`](examples/public_demo/)
+- **Cross-Repository Evidence Map**: [Ecosystem Evidence Flow](https://github.com/tmolavi/geo-scope/blob/main/docs/EVIDENCE_MAP.md)
+
+* **Prompts Generated & Stratified**: 30 standardized queries.
+* **Strict Demand Provenance Separation**:
+  * **Observed User Demand ($N=15$)**: Extracted from genuine conversational search logs (`source_type: "observed"`).
+  * **Exploration Hypotheses ($N=15$)**: Systematic template variations (`source_type: "generated"`).
+* **5 Intent Strata**: `commercial` (general evaluation), `compare` (head-to-head alternatives), `trust` (credibility & contracts), `solve` (technical fixes), and `buy` (procurement & quotes).
+* **Provenance Contract Schema**:
+  ```json
+  {
+    "id": "PRM-IR-001",
+    "prompt": "بهترین آژانس دیجیتال مارکتینگ و سئو در ایران کدام است؟",
+    "intent": "commercial",
+    "source_type": "observed",
+    "source_reference": "answerpath",
+    "cluster": "general_recommendation"
+  }
+  ```
+* **Ecosystem Architecture**: See [Benchmark Ecosystem Map](docs/BENCHMARK_ECOSYSTEM.md) for data flow across AnswerPath, GEO-Scope, SAGE, MAVI, and SiteProbe.
+
+## 🏛️ Ecosystem
+
+AnswerPath GEO operates as the question discovery component of the **Molavi AI Visibility Stack**:
+
+- **Discovery**: [AnswerPath GEO](https://github.com/tmolavi/answerpath-geo)
+- **Measurement**: [GEO-Scope](https://github.com/tmolavi/geo-scope)
+- **Diagnostics**: [SAGE Audit](https://github.com/tmolavi/sage-audit)
+- **Action**: [SiteProbe](https://github.com/tmolavi/siteprobe)
+- **Protocol**: [MCP GEO Server](https://github.com/tmolavi/mcp-geo-server)
+
+## 📖 Runnable Python Example
+
+Run the bundled discovery example script:
+```bash
+python examples/discover_example.py
+```
+Sample benchmark query payload is available in [`examples/sample_queries.json`](examples/sample_queries.json).
+
+## MCP setup
+
+AnswerPath exposes one MCP tool, `discover_questions`. The stdio transport works with local Codex, Antigravity, Claude Desktop, Cursor, Windsurf and other MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "answerpath": {
+      "command": "/absolute/path/to/answerpath-geo/.venv/bin/answerpath",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Ask the client to call `discover_questions` with `topic`, optional owned `inputs` (`text` and `source`), and `include_generated`. Generated prompts are always labeled separately from observed questions.
+
+For a private Cloud deployment, run the HTTP transport behind HTTPS and an authentication gateway:
+
+```bash
+answerpath serve-mcp --host 127.0.0.1 --port 8787
+```
+
+The JSON-RPC endpoint is `POST /mcp`. The application deliberately does not implement authentication itself: put it behind your gateway, rate limits and tenant isolation before exposing it publicly. A public URL or a successful protocol handshake does not prove that provider data is available.
+
+## Privacy and data boundaries
+
+Processing is local and deterministic. AnswerPath does not transmit input files. Do not place private exports in a public repository or commit generated files containing message content. Remove or hash identifiers before sharing results. Only analyze data for which you have authorization.
+
+## Development & Testing
+
+```bash
+pip install -e .
+pytest tests/ -v
+```
+
+## 💬 Community & External Collaboration
+
+We welcome contributions to query mining, clustering algorithms, and demand stratification:
+
+- **Discussions**: [GitHub Discussions](https://github.com/tmolavi/answerpath-geo/discussions)
+- **First Contribution Guide**: [`docs/FIRST_CONTRIBUTION.md`](docs/FIRST_CONTRIBUTION.md)
+- **Research Collaboration**: [`docs/RESEARCH_COLLABORATION.md`](docs/RESEARCH_COLLABORATION.md)
+- **Issues & Bug Reports**: [GitHub Issues](https://github.com/tmolavi/answerpath-geo/issues)
+- **Contribution Standards**: [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`SECURITY.md`](SECURITY.md)
+
+## 👤 Author & License
+
+Developed by **Taghi Molavi** — [molavi.pro](https://molavi.pro)  
+MIT. See [LICENSE](LICENSE).
+

answerpath_geo-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+answerpath_geo/__init__.py,sha256=74c9eCha9046cIp-PMNSnBUcd_a8qJDUvNINexu4f0I,100
+answerpath_geo/cli.py,sha256=eGgRJ14EPhDcUEvyGn_BQ85UGWzV8AU14VY_EKE1z-Q,1231
+answerpath_geo/core.py,sha256=MRl0G9GLEVn4SNyTOyFvIBgWTRrJWVuV2o6bgD-DNuU,5372
+answerpath_geo/mcp.py,sha256=GmxL_Pj5EsZ73Wes3pWHveV6oF-_Tuu-giHiFcmFVmc,2615
+answerpath_geo-0.1.0.dist-info/licenses/LICENSE,sha256=RC3FG5W-RXeuM6BrTIPuC9ODjHlX_qkVKiYsc2ouQNc,1068
+answerpath_geo-0.1.0.dist-info/METADATA,sha256=YLUqWSAtDTKOsvNdCyFd7vLNrEJzwEoPXwRRuy8qF_c,10405
+answerpath_geo-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+answerpath_geo-0.1.0.dist-info/entry_points.txt,sha256=X1XFlUaTP5M7_v2smS5bZTwvbCTSh_SU-4kryl5a6DU,55
+answerpath_geo-0.1.0.dist-info/top_level.txt,sha256=gk02kBXcMP-1zD4ruyD8E6WJoPuppS-nvQ0auEMXook,15
+answerpath_geo-0.1.0.dist-info/RECORD,,

answerpath_geo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

answerpath_geo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+answerpath = answerpath_geo.cli:main

answerpath_geo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taqi Molavi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

answerpath_geo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+answerpath_geo