geosition 4.9.1__py3-none-any.whl

geo_optimizer/__init__.py

@@ -0,0 +1,78 @@
+"""
+GEOSITION — Generative Engine Optimization Toolkit
+
+Make websites visible and citable by AI search engines
+(ChatGPT, Perplexity, Claude, Gemini).
+
+Based on the Princeton KDD 2024 research paper (arxiv.org/abs/2311.09735).
+
+Programmatic usage::
+
+    from geo_optimizer import audit, AuditResult
+    result = audit("https://example.com")
+    print(result.score, result.band)
+"""
+
+from __future__ import annotations
+
+import warnings
+
+# Suppress persistent urllib3 LibreSSL runtime warning in CLI contexts.
+warnings.filterwarnings(
+    "ignore",
+    message=r"urllib3 v2 only supports OpenSSL 1\.1\.1\+.*",
+    category=Warning,
+)
+
+__version__ = "4.9.1"
+
+# ─── Public API ──────────────────────────────────────────────────────────────
+
+from geo_optimizer.core.audit import run_full_audit as audit  # noqa: E402
+from geo_optimizer.core.audit import run_full_audit_async as audit_async  # noqa: E402
+from geo_optimizer.core.registry import AuditCheck, CheckRegistry, CheckResult  # noqa: E402
+from geo_optimizer.models.results import (  # noqa: E402
+    AuditResult,
+    CitabilityResult,
+    ContentResult,
+    FixItem,
+    FixPlan,
+    LlmsTxtResult,
+    MetaResult,
+    MethodScore,
+    NextAction,
+    RobotsResult,
+    SchemaAnalysis,
+    SchemaResult,
+    SitemapUrl,
+    VerticalAuditResult,
+    VerticalSignal,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main functions
+    "audit",
+    "audit_async",
+    # Plugin system
+    "CheckRegistry",
+    "AuditCheck",
+    "CheckResult",
+    # Result dataclasses
+    "AuditResult",
+    "RobotsResult",
+    "LlmsTxtResult",
+    "SchemaResult",
+    "MetaResult",
+    "ContentResult",
+    "CitabilityResult",
+    "MethodScore",
+    "NextAction",
+    "FixPlan",
+    "FixItem",
+    "SchemaAnalysis",
+    "SitemapUrl",
+    "VerticalAuditResult",
+    "VerticalSignal",
+]

geo_optimizer/cli/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

geo_optimizer/cli/agent_cmd.py

@@ -0,0 +1,143 @@
+"""
+CLI command: geo agent
+
+Generates WebMCP / tool-calling ready endpoints so AI agents can use your
+site as a tool. Future-proofs for the agent era.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from geo_optimizer.core.agent_endpoints import run_agent_endpoint_generator
+from geo_optimizer.utils.validators import validate_public_url
+
+
+@click.command("agent")
+@click.option("--url", required=True, help="URL of the site to prepare for AI agents")
+@click.option(
+    "--output-dir",
+    default="./agent-endpoints",
+    show_default=True,
+    help="Directory to write generated endpoint files",
+)
+@click.option(
+    "--apply",
+    "do_apply",
+    is_flag=True,
+    help="Write files to output directory (default: preview only)",
+)
+def agent_cmd(url: str, output_dir: str, do_apply: bool) -> None:
+    """Generate WebMCP / tool-calling endpoints for AI agent access.
+
+    Makes your site callable as a tool by AI agents (Claude, ChatGPT,
+    Perplexity, etc.). Generates the full endpoint stack:
+
+    \b
+      .well-known/ai.txt    — agent declaration
+      ai/summary.json       — machine-readable site identity
+      ai/faq.json           — answers agents can surface directly
+      ai/service.json       — service capabilities
+      ai/tools.json         — WebMCP tool definitions
+      + potentialAction JSON-LD and WebMCP HTML snippets
+
+    \b
+    Examples:
+      geo agent --url https://yoursite.com
+      geo agent --url https://yoursite.com --apply
+      geo agent --url https://yoursite.com --apply --output-dir ./public
+    """
+    # Validate URL
+    safe, reason = validate_public_url(url)
+    safe_url = url.rstrip("/")
+    if not safe:
+        click.echo(f"\n❌ Unsafe URL: {reason}", err=True)
+        sys.exit(1)
+
+    click.echo(f"🤖 Checking agent readiness for {safe_url} ...", err=True)
+
+    result = run_agent_endpoint_generator(safe_url)
+
+    # Status summary
+    click.echo(f"\n📊 Agent Readiness — {result.endpoints_present}/5 endpoints present\n")
+
+    checks = [
+        ("/.well-known/ai.txt", result.has_well_known_ai),
+        ("/ai/summary.json", result.has_summary),
+        ("/ai/faq.json", result.has_faq),
+        ("/ai/service.json", result.has_service),
+        ("/ai/tools.json", result.has_tools),
+    ]
+    for path, present in checks:
+        icon = "✅" if present else "❌"
+        click.echo(f"  {icon}  {path}")
+
+    if result.agent_ready:
+        click.echo("\n✅ Site is agent-ready!\n")
+    else:
+        click.echo(f"\n⚠️  {5 - result.endpoints_present} endpoint(s) missing — generating now...\n")
+
+    if not result.files:
+        click.echo("Nothing to generate — all endpoints already present.")
+        _show_snippets(result)
+        return
+
+    # List what will be generated
+    click.echo(f"📋 {len(result.files)} file(s) to generate:\n")
+    for f in result.files:
+        click.echo(f"  → {f.path}")
+        click.echo(f"     {f.description}\n")
+
+    if not do_apply:
+        # Preview mode
+        click.echo("=" * 60)
+        click.echo("PREVIEW (use --apply to write the files)")
+        click.echo("=" * 60)
+        for f in result.files:
+            click.echo(f"\n{'─' * 40}")
+            click.echo(f"📄 {f.path}")
+            click.echo(f"{'─' * 40}")
+            lines = f.content.splitlines()
+            if len(lines) > 25:
+                click.echo("\n".join(lines[:25]))
+                click.echo(f"\n  ... ({len(lines) - 25} more lines)")
+            else:
+                click.echo(f.content)
+
+        click.echo(f"\n💡 Run: geo agent --url {url} --apply")
+    else:
+        # Write files
+        out = Path(output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        for f in result.files:
+            dest = out / f.path
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(f.content, encoding="utf-8")
+            click.echo(f"  ✅ {dest}")
+
+        click.echo(f"\n✅ {len(result.files)} file(s) written to {out}/")
+        click.echo("\n📁 Deploy these files to your web root so agents can reach them at:")
+        for f in result.files:
+            click.echo(f"   {safe_url}/{f.path}")
+
+    _show_snippets(result)
+
+
+def _show_snippets(result) -> None:
+    """Print developer snippets (always shown, not written to disk)."""
+    if not result.snippets:
+        return
+
+    click.echo("\n" + "=" * 60)
+    click.echo("DEVELOPER SNIPPETS — add these to your site code")
+    click.echo("=" * 60)
+
+    for s in result.snippets:
+        click.echo(f"\n{'─' * 40}")
+        click.echo(f"📎 {s.path}")
+        click.echo(f"   {s.description}")
+        click.echo(f"{'─' * 40}")
+        click.echo(s.content)

geo_optimizer/cli/apply_cmd.py

@@ -0,0 +1,75 @@
+"""
+CLI command: geo apply
+
+Apply generated GEO fixes directly to a local repository with stack-aware routing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.command(name="apply")
+@click.option("--url", required=True, help="Site URL to audit and generate fixes from")
+@click.option("--repo", "repo_path", default=".", show_default=True, help="Local repo path to apply fixes into")
+@click.option(
+    "--only",
+    default=None,
+    help="Filter categories: robots,llms,schema,meta,ai_discovery,content,vertical",
+)
+@click.option(
+    "--vertical",
+    default="auto",
+    type=click.Choice(
+        [
+            "auto",
+            "generic",
+            "ecommerce-retail",
+            "travel-hospitality",
+            "healthcare-dental",
+            "real-estate-proptech",
+            "legal-professional-services",
+            "manufacturing-industrial-b2b",
+            "financial-services-insurance",
+            "saas-technology",
+            "education-edtech-k12",
+            "local-home-services",
+        ],
+        case_sensitive=False,
+    ),
+    show_default=True,
+)
+@click.option(
+    "--market-locale",
+    default="en",
+    type=click.Choice(["en", "fr", "en-fr"], case_sensitive=False),
+    show_default=True,
+)
+def apply_cmd(url, repo_path, only, vertical, market_locale):
+    """Run audit+fix and apply file-safe fixes to a local project."""
+    from geo_optimizer.core.audit import run_full_audit
+    from geo_optimizer.core.fixer import run_all_fixes
+    from geo_optimizer.core.site_integrator import apply_fix_plan_to_repo
+
+    only_set = {c.strip().lower() for c in only.split(",")} if only else None
+
+    click.echo("⏳ Running audit and generating fix plan...", err=True)
+    result = run_full_audit(url, vertical=vertical, market_locale=market_locale)
+    plan = run_all_fixes(url=url, audit_result=result, only=only_set)
+
+    if not plan.fixes:
+        click.echo("✅ No applicable fixes generated.")
+        return
+
+    repo = Path(repo_path).resolve()
+    outcome = apply_fix_plan_to_repo(repo, plan.fixes)
+
+    click.echo(f"✅ Applied GEO fixes into: {repo}")
+    click.echo(f"Stack detected: {outcome.stack}")
+    click.echo(f"Applied files: {len(outcome.applied_files)}")
+    for p in outcome.applied_files[:20]:
+        click.echo(f"  - {p}")
+    if outcome.manual_steps:
+        click.echo("⚠️  Manual snippet steps recorded in geo-manual-steps.md")