autonitia-intel 0.2.0__py3-none-any.whl

autonitia_intel/__init__.py

@@ -0,0 +1,27 @@
+"""
+autonitia-intel — open-source business-website profile extractor.
+
+The FREE engine turns any business website into a clean structured profile
+(company facts, contact details, social presence, detected tools/capabilities)
+plus a *pro_features* count of opportunities. The intelligence layer — verified
+signals, scoring, offer matching, outreach — is Autonitia Intel Pro, which
+imports these same building blocks.
+
+Quick start:
+
+    from autonitia_intel import ProfileGraph
+
+    graph = ProfileGraph(lens="automation")          # bring your own key via env or args
+    profile = graph.run("https://example.com")
+    print(profile.model_dump_json(indent=2))
+
+Bring your own model key:
+
+    ProfileGraph(api_key="sk-...", model="gpt-4o-mini")
+"""
+
+from .graph import ProfileGraph
+from .models import CompanyProfile, ProfileResult
+
+__version__ = "0.2.0"
+__all__ = ["ProfileGraph", "CompanyProfile", "ProfileResult"]

autonitia_intel/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

autonitia_intel/cli.py

@@ -0,0 +1,56 @@
+"""
+CLI: autonitia-intel analyse — extract a company profile (+ opportunity pro_features).
+
+Example:
+    python -m autonitia_intel analyse --target-url https://example.com --lens automation
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config import OUTPUT_DIR
+from .graph import ProfileGraph
+from .lenses import LENSES
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="autonitia-intel", description="Business-website profile extractor (free tier).")
+    sub = parser.add_subparsers(dest="command")
+
+    a = sub.add_parser("analyse", help="Extract a profile from a business website")
+    a.add_argument("--target-url", required=True)
+    a.add_argument("--lens", default="automation", choices=LENSES, help="Lens used only for the opportunity pro_features count")
+    a.add_argument("--api-key", default=None, help="Bring your own model key (overrides env)")
+    a.add_argument("--model", default=None, help="Model id (overrides env)")
+    a.add_argument("--no-cache", action="store_true")
+    a.add_argument("--no-telemetry", action="store_true")
+    a.add_argument("--quiet", action="store_true")
+
+    args = parser.parse_args(argv)
+    if args.command != "analyse":
+        parser.print_help()
+        sys.exit(1)
+
+    graph = ProfileGraph(
+        lens=args.lens,
+        telemetry=not args.no_telemetry,
+        verbose=not args.quiet,
+        api_key=args.api_key,
+        model=args.model,
+    )
+    if not args.quiet:
+        print(f"Analysing {args.target_url} (lens={args.lens}) ...")
+    result = graph.run(args.target_url, use_cache=not args.no_cache)
+
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    name = (result.target_company.name or "result").replace("/", "_").replace(" ", "_")
+    path = OUTPUT_DIR / f"{name}_profile.json"
+    path.write_text(result.model_dump_json(indent=2))
+
+    print(f"\nSaved: {path}\n")
+    print(result.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    main()

autonitia_intel/config.py

@@ -0,0 +1,36 @@
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
+MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+
+BROWSER_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/125.0.0.0 Safari/537.36"
+    ),
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+CACHE_DIR = Path(__file__).parent.parent / "output" / ".cache"
+OUTPUT_DIR = Path(__file__).parent.parent / "output"
+REQUEST_TIMEOUT = 15
+MAX_CONTENT_CHARS = 24_000   # overall budget sent to the LLM
+PER_PAGE_CHARS = 6_000       # per-page cap so no single page (e.g. a bloated homepage) starves the rest
+MAX_SUBPAGES = 3
+
+# Crawling politeness/resilience
+RESPECT_ROBOTS = os.getenv("AUTONITIA_RESPECT_ROBOTS", "true").lower() != "false"
+FETCH_RETRIES = int(os.getenv("AUTONITIA_FETCH_RETRIES", "2"))   # extra attempts on transient errors
+ROBOTS_UA = "autonitia-intel"
+
+# Telemetry — see telemetry/telemetry.py. Nothing is sent over the network in v0.1.
+# Level 1 (execution metrics) is opt-OUT. Level 2 (dataset capture) is opt-IN.
+TELEMETRY_ENABLED = os.getenv("AUTONITIA_TELEMETRY", "true").lower() != "false"
+DATASET_CONTRIBUTION = os.getenv("AUTONITIA_DATASET", "false").lower() == "true"

autonitia_intel/detection/__init__.py

@@ -0,0 +1,4 @@
+from .capabilities import detect_capabilities, extract_contacts
+from .fingerprints import detect_tools
+
+__all__ = ["detect_capabilities", "detect_tools", "extract_contacts"]

autonitia_intel/detection/capabilities.py

@@ -0,0 +1,136 @@
+"""
+Deterministic capability + digital-presence detection.
+
+Inspects raw HTML across all fetched pages to determine observable facts:
+lead-capture methods, social links, SEO basics, tracking. No LLM.
+
+These are FACTS (present/absent), which become the evidence base for signals.
+"""
+
+import re
+
+from ..detection.fingerprints import detect_tools
+from ..models import Capabilities, SEO, SocialMedia, Tracking
+
+SOCIAL_PATTERNS = {
+    "facebook": r"https?://(?:www\.)?facebook\.com/[A-Za-z0-9_.\-/]+",
+    "instagram": r"https?://(?:www\.)?instagram\.com/[A-Za-z0-9_.\-/]+",
+    "linkedin": r"https?://(?:[a-z]{2}\.)?linkedin\.com/(?:company|in)/[A-Za-z0-9_.\-/]+",
+    "tiktok": r"https?://(?:www\.)?tiktok\.com/@[A-Za-z0-9_.\-/]+",
+    "youtube": r"https?://(?:www\.)?youtube\.com/[A-Za-z0-9_.\-/@]+",
+    "x": r"https?://(?:www\.)?(?:twitter|x)\.com/[A-Za-z0-9_]+",
+}
+
+# STRONG patterns = a real third-party tool / explicit URL → trustworthy, the
+# LLM verifier may NOT downgrade these. WEAK patterns = generic text heuristics
+# ("book now") that are easily wrong → the LLM verifier MAY override them.
+BOOKING_STRONG = [r"calendly\.com", r"fresha\.com", r"acuityscheduling\.com", r"booksy\.com",
+                  r"simplybook\.(me|it)", r"setmore\.com", r"squareup\.com/appointments"]
+BOOKING_WEAK = [r"book\s*now", r"book\s*online", r"schedule\s*(an?\s*)?appointment", r"book\s*a\s*viewing"]
+
+LIVE_CHAT_STRONG = [r"intercom", r"driftt?\.com", r"tidio", r"tawk\.to", r"crisp\.chat", r"hs-scripts"]
+LIVE_CHAT_WEAK = [r"livechat", r"chat\s*with\s*us", r"live\s*chat"]
+
+WHATSAPP_STRONG = [r"wa\.me/", r"api\.whatsapp\.com", r"whatsapp://", r"web\.whatsapp\.com",
+                   r"chat\.whatsapp\.com", r"wa\.link/"]
+WHATSAPP_WEAK = [r"click\s*to\s*whatsapp", r'aria-label=["\'][^"\']*whatsapp', r"whatsapp\s*us"]
+
+NEWSLETTER_STRONG = [r"chimpstatic", r"klaviyo", r"list-manage\.com"]
+NEWSLETTER_WEAK = [r"newsletter", r"subscribe"]
+
+# These have no reliable "strong" structural signal — treat as weak (downgradable).
+PRICING_WEAK = [r"/pricing", r">\s*pricing\s*<", r">\s*plans\s*<", r"per\s*month", r"/mo\b"]
+CASE_STUDY_WEAK = [r"case\s*stud", r"success\s*stor", r"/portfolio", r"testimonial"]
+FORM_WEAK = [r"<form[\s>]"]  # a <form> could be search/login, not a contact form → downgradable
+
+PHONE_PATTERN = r"tel:\+?[\d\s\-()]{7,}"
+EMAIL_PATTERN = r"mailto:[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+"
+
+# Capabilities the LLM verifier is allowed to downgrade when only a WEAK signal fired.
+DOWNGRADABLE = {"has_online_booking", "has_whatsapp", "has_live_chat",
+                "has_pricing", "has_case_studies", "has_contact_form", "has_newsletter"}
+
+
+def _any(patterns: list[str], html: str) -> bool:
+    return any(re.search(p, html, re.IGNORECASE) for p in patterns)
+
+
+_EMAIL_RE = re.compile(r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}")
+_TEL_RE = re.compile(r'tel:(\+?[\d\s\-()]{7,})', re.IGNORECASE)
+_WA_RE = re.compile(r'(https?://(?:wa\.me|wa\.link|api\.whatsapp\.com|web\.whatsapp\.com|chat\.whatsapp\.com)/[^\s"\'<>]+)', re.IGNORECASE)
+
+
+def extract_contacts(html: str) -> dict:
+    """Deterministic contact extraction — a backstop/merge for the LLM output."""
+    emails = sorted({m.group(0) for m in _EMAIL_RE.finditer(html)
+                     if not m.group(0).lower().endswith((".png", ".jpg", ".gif", ".webp", ".svg"))})
+    phones = sorted({re.sub(r"\s+", " ", m.group(1)).strip() for m in _TEL_RE.finditer(html)})
+    wa = ""
+    m = _WA_RE.search(html)
+    if m:
+        wa = m.group(1)
+    return {"emails": emails, "phones": phones, "whatsapp": wa}
+
+
+def detect_capabilities(combined_html: str):
+    """
+    Returns (capabilities, social, seo, tracking, tools, strongly_detected).
+
+    `strongly_detected` is the set of capability names backed by a STRONG
+    structural signal (a real tool/URL). The LLM verifier may only downgrade
+    capabilities NOT in this set.
+    """
+    booking_strong = _any(BOOKING_STRONG, combined_html)
+    chat_strong = _any(LIVE_CHAT_STRONG, combined_html)
+    wa_strong = _any(WHATSAPP_STRONG, combined_html)
+    news_strong = _any(NEWSLETTER_STRONG, combined_html)
+
+    caps = Capabilities(
+        has_phone=bool(re.search(PHONE_PATTERN, combined_html, re.IGNORECASE)),
+        has_email=bool(re.search(EMAIL_PATTERN, combined_html, re.IGNORECASE)),
+        has_contact_form=_any(FORM_WEAK, combined_html),
+        has_whatsapp=wa_strong or _any(WHATSAPP_WEAK, combined_html),
+        has_online_booking=booking_strong or _any(BOOKING_WEAK, combined_html),
+        has_live_chat=chat_strong or _any(LIVE_CHAT_WEAK, combined_html),
+        has_pricing=_any(PRICING_WEAK, combined_html),
+        has_case_studies=_any(CASE_STUDY_WEAK, combined_html),
+        has_newsletter=news_strong or _any(NEWSLETTER_WEAK, combined_html),
+    )
+
+    strongly_detected = set()
+    if booking_strong:
+        strongly_detected.add("has_online_booking")
+    if chat_strong:
+        strongly_detected.add("has_live_chat")
+    if wa_strong:
+        strongly_detected.add("has_whatsapp")
+    if news_strong:
+        strongly_detected.add("has_newsletter")
+
+    social = SocialMedia()
+    for field, pattern in SOCIAL_PATTERNS.items():
+        m = re.search(pattern, combined_html, re.IGNORECASE)
+        if m:
+            # Skip share/intent links — keep only profile-looking URLs
+            url = m.group(0)
+            if "sharer" not in url and "intent" not in url and "/share" not in url:
+                setattr(social, field, url)
+    caps.has_social_links = any(getattr(social, f) for f in SOCIAL_PATTERNS)
+
+    seo = SEO(
+        title_tag_present=bool(re.search(r"<title[\s>]", combined_html, re.IGNORECASE)),
+        meta_description_present=bool(re.search(r'<meta[^>]+name=["\']description["\']', combined_html, re.IGNORECASE)),
+    )
+
+    tools = detect_tools(combined_html)
+    tool_names = {t["name"] for t in tools}
+    tracking = Tracking(
+        google_analytics="Google Analytics" in tool_names,
+        google_tag_manager="Google Tag Manager" in tool_names,
+        meta_pixel="Meta Pixel" in tool_names,
+        tiktok_pixel="TikTok Pixel" in tool_names,
+        linkedin_pixel="LinkedIn Insight" in tool_names,
+        hotjar="Hotjar" in tool_names,
+    )
+
+    return caps, social, seo, tracking, tools, strongly_detected

autonitia_intel/detection/fingerprints.py

@@ -0,0 +1,63 @@
+"""
+Deterministic technology detection.
+
+A pragmatic subset of Wappalyzer-style fingerprints: each entry matches a
+substring/regex in the raw HTML. NO LLM involved — this is fact, not inference,
+which is why it's the most defensible signal in the product.
+
+For production, swap this dict for the full Wappalyzer fingerprint database
+(https://github.com/enthec/webappanalyzer) — same matching approach, ~3000 apps.
+"""
+
+import re
+
+# name -> (category, [patterns], confidence)
+FINGERPRINTS: dict[str, tuple[str, list[str], float]] = {
+    # CMS / site builders
+    "WordPress": ("cms", [r"wp-content", r"wp-includes"], 0.92),
+    "Shopify": ("ecommerce", [r"cdn\.shopify\.com", r"Shopify\.theme"], 0.95),
+    "Wix": ("cms", [r"static\.wixstatic\.com", r"_wixCssImports"], 0.9),
+    "Webflow": ("cms", [r"assets\.website-files\.com", r"webflow\.js", r"wf-"], 0.88),
+    "Squarespace": ("cms", [r"squarespace", r"static1\.squarespace\.com"], 0.9),
+    "WooCommerce": ("ecommerce", [r"woocommerce", r"wc-ajax"], 0.85),
+    # Analytics / tracking
+    "Google Analytics": ("analytics", [r"google-analytics\.com", r"gtag\(", r"ga\('create'"], 0.9),
+    "Google Tag Manager": ("analytics", [r"googletagmanager\.com"], 0.92),
+    "Meta Pixel": ("marketing_tracking", [r"fbq\(", r"connect\.facebook\.net/[a-z_]+/fbevents\.js"], 0.93),
+    "TikTok Pixel": ("marketing_tracking", [r"analytics\.tiktok\.com"], 0.9),
+    "LinkedIn Insight": ("marketing_tracking", [r"snap\.licdn\.com"], 0.9),
+    "Hotjar": ("analytics", [r"static\.hotjar\.com", r"hotjar"], 0.85),
+    # CRM / marketing / chat
+    "HubSpot": ("crm", [r"js\.hs-scripts\.com", r"hs-scripts"], 0.9),
+    "Intercom": ("live_chat", [r"widget\.intercom\.io", r"intercomSettings"], 0.9),
+    "Drift": ("live_chat", [r"js\.driftt\.com", r"drift\.com"], 0.88),
+    "Tidio": ("live_chat", [r"code\.tidio\.co"], 0.9),
+    "Tawk.to": ("live_chat", [r"embed\.tawk\.to"], 0.9),
+    "Crisp": ("live_chat", [r"client\.crisp\.chat"], 0.9),
+    "Mailchimp": ("email_marketing", [r"chimpstatic\.com", r"list-manage\.com"], 0.85),
+    "Klaviyo": ("email_marketing", [r"klaviyo"], 0.85),
+    # Booking / forms
+    "Calendly": ("booking", [r"calendly\.com"], 0.92),
+    "Fresha": ("booking", [r"fresha\.com"], 0.9),
+    "Acuity Scheduling": ("booking", [r"acuityscheduling\.com"], 0.9),
+    "Booksy": ("booking", [r"booksy\.com"], 0.9),
+    "SimplyBook": ("booking", [r"simplybook\.(me|it)"], 0.88),
+    "Typeform": ("forms", [r"typeform\.com"], 0.88),
+    "Jotform": ("forms", [r"jotform\.com"], 0.88),
+}
+
+
+def detect_tools(html: str) -> list[dict]:
+    """Return a list of detected tools: {name, category, confidence, evidence}."""
+    found = []
+    for name, (category, patterns, confidence) in FINGERPRINTS.items():
+        for pat in patterns:
+            if re.search(pat, html, re.IGNORECASE):
+                found.append({
+                    "name": name,
+                    "category": category,
+                    "confidence": confidence,
+                    "evidence": f"matched /{pat}/",
+                })
+                break
+    return found

autonitia_intel/fetchers/__init__.py

@@ -0,0 +1,4 @@
+from .fetcher import fetch_html
+from .robots import RobotsDisallowed, allowed
+
+__all__ = ["fetch_html", "RobotsDisallowed", "allowed"]

autonitia_intel/fetchers/fetcher.py

@@ -0,0 +1,146 @@
+"""
+3-tier fetch: requests → cloudscraper → Playwright. Auto-escalation.
+Returns raw HTML. Caching is keyed by URL with a 24h TTL.
+"""
+
+import hashlib
+import json
+import time
+from pathlib import Path
+
+import requests
+
+from ..config import BROWSER_HEADERS, CACHE_DIR, FETCH_RETRIES, REQUEST_TIMEOUT
+from .robots import RobotsDisallowed, allowed
+
+TTL_SECONDS = 86400
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+def _cache_path(url: str) -> Path:
+    return CACHE_DIR / f"{hashlib.sha256(url.encode()).hexdigest()[:16]}.json"
+
+
+def _cache_get(url: str) -> str | None:
+    p = _cache_path(url)
+    if not p.exists():
+        return None
+    data = json.loads(p.read_text())
+    if time.time() - data["ts"] > TTL_SECONDS:
+        p.unlink()
+        return None
+    return data["html"]
+
+
+def _cache_put(url: str, html: str) -> None:
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    _cache_path(url).write_text(json.dumps({"ts": time.time(), "url": url, "html": html}))
+
+
+def _is_blocked(html: str, status: int) -> bool:
+    if status in (403, 503):
+        return True
+    snippet = html[:3000].lower()
+    return any(s in snippet for s in [
+        "just a moment", "captcha", "enable javascript",
+        "challenge-platform", "cf-browser-verification", "attention required",
+    ])
+
+
+def _is_thin(html: str, min_chars: int = 600) -> bool:
+    """
+    JS-rendered pages often return a near-empty shell to plain `requests`.
+    If the visible text is tiny, escalate to a real browser so we don't miss
+    content (addresses, WhatsApp links, etc.) that loads client-side.
+    """
+    from bs4 import BeautifulSoup
+    soup = BeautifulSoup(html, "lxml")
+    for tag in soup(["script", "style", "noscript"]):
+        tag.decompose()
+    return len(soup.get_text(strip=True)) < min_chars
+
+
+def _insufficient(html: str, status: int) -> bool:
+    return _is_blocked(html, status) or _is_thin(html)
+
+
+def _via_cloudscraper(url: str) -> str:
+    import cloudscraper
+    scraper = cloudscraper.create_scraper(browser={"browser": "chrome", "platform": "darwin", "mobile": False})
+    resp = scraper.get(url, timeout=REQUEST_TIMEOUT)
+    resp.raise_for_status()
+    return resp.text
+
+
+def _via_playwright(url: str) -> str:
+    from playwright.sync_api import sync_playwright
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        ctx = browser.new_context(user_agent=BROWSER_HEADERS["User-Agent"], locale="en-US",
+                                  viewport={"width": 1920, "height": 1080})
+        page = ctx.new_page()
+        page.goto(url, wait_until="domcontentloaded", timeout=60_000)
+        try:
+            page.wait_for_load_state("networkidle", timeout=12_000)
+        except Exception:
+            pass
+        page.wait_for_timeout(4000)
+        html = page.content()
+        browser.close()
+    return html
+
+
+def _tier1_with_retry(url: str) -> str | None:
+    """Plain requests with exponential backoff on transient errors. None → escalate."""
+    session = requests.Session()
+    session.headers.update(BROWSER_HEADERS)
+    for attempt in range(FETCH_RETRIES + 1):
+        try:
+            resp = session.get(url, timeout=REQUEST_TIMEOUT, allow_redirects=True)
+            if resp.status_code in _RETRYABLE_STATUS and attempt < FETCH_RETRIES:
+                time.sleep(0.5 * (2 ** attempt))   # 0.5s, 1s, 2s …
+                continue
+            if not _insufficient(resp.text, resp.status_code):
+                resp.raise_for_status()
+                return resp.text
+            return None  # blocked/thin → escalate to cloudscraper/Playwright
+        except requests.RequestException:
+            if attempt < FETCH_RETRIES:
+                time.sleep(0.5 * (2 ** attempt))
+                continue
+            return None
+    return None
+
+
+def fetch_html(url: str, use_cache: bool = True) -> str:
+    if use_cache:
+        cached = _cache_get(url)
+        if cached:
+            return cached
+
+    # Politeness: respect robots.txt before any network fetch.
+    if not allowed(url):
+        raise RobotsDisallowed(f"robots.txt disallows fetching {url}")
+
+    # Tier 1: requests with retry/backoff (escalate on bot-block OR thin JS shell)
+    html = _tier1_with_retry(url)
+    if html is not None:
+        if use_cache:
+            _cache_put(url, html)
+        return html
+
+    # Tier 2: cloudscraper
+    try:
+        html = _via_cloudscraper(url)
+        if not _insufficient(html, 200):
+            if use_cache:
+                _cache_put(url, html)
+            return html
+    except Exception:
+        pass
+
+    # Tier 3: Playwright (full JS render)
+    html = _via_playwright(url)
+    if use_cache:
+        _cache_put(url, html)
+    return html

autonitia_intel/fetchers/robots.py

@@ -0,0 +1,50 @@
+"""
+robots.txt awareness — polite, opt-out crawling.
+
+Before fetching, we check the target's robots.txt for our agent. Results are
+cached per-domain. If robots.txt is missing/unreachable we default to ALLOW
+(standard behaviour). Disabled with AUTONITIA_RESPECT_ROBOTS=false.
+"""
+
+from urllib.parse import urlparse
+from urllib.robotparser import RobotFileParser
+
+import requests
+
+from ..config import BROWSER_HEADERS, RESPECT_ROBOTS, ROBOTS_UA
+
+_CACHE: dict[str, RobotFileParser | None] = {}
+
+
+class RobotsDisallowed(Exception):
+    """Raised when robots.txt disallows fetching a URL."""
+
+
+def _parser_for(domain_root: str) -> RobotFileParser | None:
+    if domain_root in _CACHE:
+        return _CACHE[domain_root]
+    rp = RobotFileParser()
+    try:
+        resp = requests.get(f"{domain_root}/robots.txt", headers=BROWSER_HEADERS, timeout=8)
+        if resp.status_code >= 400:
+            rp = None  # no robots.txt → allow all
+        else:
+            rp.parse(resp.text.splitlines())
+    except requests.RequestException:
+        rp = None
+    _CACHE[domain_root] = rp
+    return rp
+
+
+def allowed(url: str) -> bool:
+    """True if we may fetch this URL (always True when robots respect is off)."""
+    if not RESPECT_ROBOTS:
+        return True
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        return True
+    root = f"{parsed.scheme}://{parsed.netloc}"
+    rp = _parser_for(root)
+    if rp is None:
+        return True
+    return rp.can_fetch(ROBOTS_UA, url)

autonitia_intel/graph/__init__.py

@@ -0,0 +1,5 @@
+from .base_graph import END, BaseGraph
+from .base_node import BaseNode
+from .profile_graph import ProfileGraph
+
+__all__ = ["BaseGraph", "BaseNode", "END", "ProfileGraph"]

autonitia_intel/graph/base_graph.py

@@ -0,0 +1,64 @@
+"""
+Graph executor with conditional edges.
+
+A graph is: nodes (keyed by name) + an `edges` map + an `entry` node. Each edge
+value is one of:
+  - a node name (str)        → always go there next
+  - None (END)               → stop
+  - a callable(state) -> str|None → CONDITIONAL: decide the next node at runtime
+
+This makes the pipeline a real graph: branches (repair vs continue), short-circuits
+(skip the LLM when there's nothing to do), and bounded loops. Still mirrors
+LangGraph's contract so it can be swapped later. `max_steps` guards against loops.
+"""
+
+import time
+
+from .base_node import BaseNode
+
+END = None
+
+
+class BaseGraph:
+    def __init__(self, nodes: list[BaseNode], edges: dict, entry: str,
+                 verbose: bool = True, max_steps: int = 25):
+        self.nodes = {n.name: n for n in nodes}
+        self.edges = edges
+        self.entry = entry
+        self.verbose = verbose
+        self.max_steps = max_steps
+
+    def execute(self, state: dict) -> dict:
+        trace = []
+        current = self.entry
+        steps = 0
+
+        while current is not None:
+            if steps >= self.max_steps:
+                raise RuntimeError(f"Graph exceeded max_steps={self.max_steps} (possible loop)")
+            if current not in self.nodes:
+                raise KeyError(f"Edge points to unknown node '{current}'")
+
+            node = self.nodes[current]
+            start = time.time()
+            try:
+                state = node.execute(state)
+            except Exception as e:
+                elapsed = int((time.time() - start) * 1000)
+                trace.append({"node": current, "status": "error", "ms": elapsed, "error": str(e)})
+                if self.verbose:
+                    print(f"   ✗ {current} failed: {e}")
+                state["_trace"] = trace
+                state["_error"] = {"node": current, "error": str(e)}
+                raise
+            elapsed = int((time.time() - start) * 1000)
+            trace.append({"node": current, "status": "success", "ms": elapsed})
+            if self.verbose:
+                print(f"   ✓ {current} ({elapsed} ms)")
+
+            nxt = self.edges.get(current, END)
+            current = nxt(state) if callable(nxt) else nxt
+            steps += 1
+
+        state["_trace"] = trace
+        return state

autonitia_intel/graph/base_node.py

@@ -0,0 +1,13 @@
+"""
+Minimal node abstraction. Each node has a single responsibility and transforms
+a shared `state` dict. This intentionally mirrors LangGraph's node contract so
+the engine can be swapped for LangGraph later without rewriting nodes.
+"""
+
+
+class BaseNode:
+    def __init__(self, name: str | None = None):
+        self.name = name or self.__class__.__name__
+
+    def execute(self, state: dict) -> dict:  # pragma: no cover - interface
+        raise NotImplementedError