manifest-api 0.1.0__tar.gz

manifest_api-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git push *)",
+      "Bash(git -C /Users/maxnordstrom/Desktop/semantic-agent-layer status)",
+      "Bash(git -C /Users/maxnordstrom/Desktop/semantic-agent-layer diff)",
+      "Bash(git *)"
+    ]
+  }
+}

manifest_api-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.env
+session.json
+semantic/
+__pycache__/
+*.pyc

manifest_api-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: manifest-api
+Version: 0.1.0
+Summary: Python SDK for the Manifest API — structured action manifests for AI agents
+Project-URL: Homepage, https://omfang.io/docs
+Project-URL: Repository, https://github.com/omfang/manifest-api
+Project-URL: Bug Tracker, https://github.com/omfang/manifest-api/issues
+Author-email: Omfang AB <hello@omfang.io>
+License: MIT
+Keywords: agents,ai,automation,browser,manifest,web
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# manifest-api
+
+Python SDK for the [Manifest API](https://omfang.io/docs) — extracts structured action manifests from web pages so AI agents know *what they can do*, not just what's on screen.
+
+## Install
+
+```bash
+pip install manifest-api
+```
+
+## Quickstart
+
+### Sync
+
+```python
+from manifest_api import ManifestClient
+
+client = ManifestClient(api_key="your-key")  # or set MANIFEST_API_KEY env var
+manifest = client.get("https://example.com")
+
+print(manifest.current_page_state)
+print(manifest.actions)
+
+# Convenience helpers
+action = manifest.action("submit-form")
+inputs = manifest.actions_of_type("input")
+required = manifest.required_actions
+```
+
+### Async
+
+```python
+import asyncio
+from manifest_api import AsyncManifestClient
+
+async def main():
+    async with AsyncManifestClient(api_key="your-key") as client:
+        manifest = await client.get("https://example.com")
+        print(manifest.current_page_state)
+
+asyncio.run(main())
+```
+
+## All methods
+
+```python
+# Both ManifestClient and AsyncManifestClient expose:
+manifest = client.get("https://example.com")   # POST /manifest → Manifest
+health   = client.health()                      # GET  /health → dict
+valid    = client.session_valid()               # GET  /session-status → bool
+```
+
+## Manifest helpers
+
+```python
+manifest.action("id")              # → Action | None
+manifest.actions_of_type("input")  # → list[Action]
+manifest.required_actions          # → list[Action]
+```
+
+## Action types
+
+`button` · `input` · `textarea` · `select` · `checkbox` · `radio` · `other`
+
+## Error handling
+
+```python
+from manifest_api import AuthenticationError, RateLimitError, APIError
+
+try:
+    manifest = client.get("https://example.com")
+except AuthenticationError:
+    print("Check your API key")
+except RateLimitError:
+    print("Slow down — rate limit hit")
+except APIError as e:
+    print(f"Server error {e.status_code}")
+```
+
+## Docs
+
+[https://omfang.io/docs](https://omfang.io/docs)

manifest_api-0.1.0/README.md

@@ -0,0 +1,82 @@
+# manifest-api
+
+Python SDK for the [Manifest API](https://omfang.io/docs) — extracts structured action manifests from web pages so AI agents know *what they can do*, not just what's on screen.
+
+## Install
+
+```bash
+pip install manifest-api
+```
+
+## Quickstart
+
+### Sync
+
+```python
+from manifest_api import ManifestClient
+
+client = ManifestClient(api_key="your-key")  # or set MANIFEST_API_KEY env var
+manifest = client.get("https://example.com")
+
+print(manifest.current_page_state)
+print(manifest.actions)
+
+# Convenience helpers
+action = manifest.action("submit-form")
+inputs = manifest.actions_of_type("input")
+required = manifest.required_actions
+```
+
+### Async
+
+```python
+import asyncio
+from manifest_api import AsyncManifestClient
+
+async def main():
+    async with AsyncManifestClient(api_key="your-key") as client:
+        manifest = await client.get("https://example.com")
+        print(manifest.current_page_state)
+
+asyncio.run(main())
+```
+
+## All methods
+
+```python
+# Both ManifestClient and AsyncManifestClient expose:
+manifest = client.get("https://example.com")   # POST /manifest → Manifest
+health   = client.health()                      # GET  /health → dict
+valid    = client.session_valid()               # GET  /session-status → bool
+```
+
+## Manifest helpers
+
+```python
+manifest.action("id")              # → Action | None
+manifest.actions_of_type("input")  # → list[Action]
+manifest.required_actions          # → list[Action]
+```
+
+## Action types
+
+`button` · `input` · `textarea` · `select` · `checkbox` · `radio` · `other`
+
+## Error handling
+
+```python
+from manifest_api import AuthenticationError, RateLimitError, APIError
+
+try:
+    manifest = client.get("https://example.com")
+except AuthenticationError:
+    print("Check your API key")
+except RateLimitError:
+    print("Slow down — rate limit hit")
+except APIError as e:
+    print(f"Server error {e.status_code}")
+```
+
+## Docs
+
+[https://omfang.io/docs](https://omfang.io/docs)

manifest_api-0.1.0/claude.md

@@ -0,0 +1,38 @@
+# semantic-agent-layer
+
+## What this is
+A proof of concept for a semantic UI layer for AI agents. Instead of scraping raw HTML or using vision models to interact with web interfaces, this project extracts structured action manifests from web pages — telling agents *what they can do* on a page, not just what's on it.
+
+The long-term vision is infrastructure that makes any webpage agent-readable natively, similar to what HTML did for browsers.
+
+## Status
+Core pipeline is working end to end. Successfully published a post to Omfang AB's LinkedIn page autonomously.
+
+## Completed
+- Define stable JSON schema for action manifests across different sites
+- Accessibility tree extraction via `page.aria_snapshot()`
+- LLM-based translation of raw snapshot to clean JSON action manifest
+- Execution layer: navigate to composer, fill post body, publish as company page
+- Session cookie persistence via `session.py` (login once, skip forever after)
+- Parameterized post text via `post_to_linkedin(text: str)`
+- Single `post_to_linkedin.py` callable by any agent
+- `manifest.py` — `get_action_manifest(url)` works on any URL, returns structured JSON
+
+## Pipeline
+1. `linkedin_snapshot.py` — captures accessibility tree of LinkedIn feed
+2. `translate-snapshot.py` — translates snapshot to clean JSON action manifest
+3. `execute_post.py` — navigates to company composer, types post, publishes
+
+## Stack
+- Python 3.13
+- Playwright (browser automation)
+- Anthropic SDK (snapshot translation)
+- python-dotenv (env vars)
+- Virtual environment: `semantic/`
+
+## Environment
+- API key loaded from `.env` via `python-dotenv`
+- Always activate venv before running: `source semantic/bin/activate`
+- Run scripts from the root `semantic-agent-layer/` folder
+
+## Next steps

manifest_api-0.1.0/db.py

@@ -0,0 +1,74 @@
+import hashlib
+import os
+import secrets
+
+import psycopg2
+from psycopg2.extras import Json
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def _conn():
+    return psycopg2.connect(
+        host=os.getenv("DB_HOST"),
+        port=os.getenv("DB_PORT", 5432),
+        dbname=os.getenv("DB_NAME"),
+        user=os.getenv("DB_USER"),
+        password=os.getenv("DB_PASSWORD"),
+    )
+
+
+def _hash(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+def verify_api_key(raw_key: str) -> bool:
+    with _conn() as conn, conn.cursor() as cur:
+        cur.execute(
+            "SELECT 1 FROM api_keys WHERE key_hash = %s AND revoked = false",
+            (_hash(raw_key),),
+        )
+        return cur.fetchone() is not None
+
+
+def create_api_key(email: str) -> str:
+    raw = secrets.token_urlsafe(32)
+    with _conn() as conn, conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO api_keys (key_hash, email) VALUES (%s, %s)",
+            (_hash(raw), email),
+        )
+    return raw
+
+
+def get_cached_manifest(url: str) -> dict | None:
+    ttl = int(os.getenv("CACHE_TTL_HOURS", "6"))
+    with _conn() as conn, conn.cursor() as cur:
+        cur.execute(
+            "SELECT manifest FROM manifest_cache WHERE url = %s AND cached_at > now() - (%s * interval '1 hour')",
+            (url, ttl),
+        )
+        row = cur.fetchone()
+    return row[0] if row else None
+
+
+def check_rate_limit(key_hash: str) -> bool:
+    limit = int(os.getenv("RATE_LIMIT_PER_MINUTE", "10"))
+    with _conn() as conn, conn.cursor() as cur:
+        cur.execute("INSERT INTO request_log (key_hash) VALUES (%s)", (key_hash,))
+        cur.execute(
+            "SELECT COUNT(*) FROM request_log WHERE key_hash = %s AND requested_at > now() - interval '60 seconds'",
+            (key_hash,),
+        )
+        count = cur.fetchone()[0]
+    return count < limit
+
+
+def save_manifest(url: str, manifest: dict) -> None:
+    with _conn() as conn, conn.cursor() as cur:
+        cur.execute(
+            """INSERT INTO manifest_cache (url, manifest, cached_at) VALUES (%s, %s, now())
+               ON CONFLICT (url) DO UPDATE SET manifest = EXCLUDED.manifest, cached_at = now()""",
+            (url, Json(manifest)),
+        )

manifest_api-0.1.0/example/fill_contact_form.py

@@ -0,0 +1,112 @@
+import json
+import os
+from urllib.parse import urljoin
+import anthropic
+from dotenv import load_dotenv
+from playwright.sync_api import sync_playwright
+from session import browser_context
+from manifest import get_action_manifest
+
+load_dotenv()
+
+_client = anthropic.Anthropic()
+
+BASE_URL = "https://omfang.io"
+
+_TEST_DATA = {
+    "name": "Agent Test",
+    "email": "test@omfang.io",
+    "subject": "Automated test from semantic agent layer",
+    "message": "This is an automated test from the semantic agent layer",
+}
+
+_FILL_PROMPT = """You have a page manifest and data to fill into a contact form.
+
+Manifest:
+{manifest}
+
+Data to fill:
+{data}
+
+Return a JSON array of fill/click instructions that will complete and submit the form.
+Each instruction is one of:
+  {{"action": "fill", "label": "<exact field label>", "value": "<value>"}}
+  {{"action": "click", "name": "<exact button text>"}}
+
+Use the exact label text from the manifest actions. End with a click on the submit button.
+Return only the JSON array, nothing else."""
+
+
+def _resolve_url(href: str | None) -> str | None:
+    if not href:
+        return None
+    return urljoin(BASE_URL, href)
+
+
+def _plan_fill(manifest: dict) -> list[dict]:
+    prompt = _FILL_PROMPT.format(
+        manifest=json.dumps(manifest, indent=2),
+        data=json.dumps(_TEST_DATA, indent=2),
+    )
+    resp = _client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=500,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    text = resp.content[0].text.strip()
+    if text.startswith("```"):
+        text = text.split("\n", 1)[1].rsplit("```", 1)[0]
+    return json.loads(text)
+
+
+def fill_contact_form() -> None:
+    # Step 1: discover contact page URL
+    print("Step 1: fetching homepage manifest...")
+    home = get_action_manifest(BASE_URL)
+    contact_nav = next(
+        n for n in home["navigation"]
+        if any(k in (n["label"] + " " + (n["url"] or "")).lower() for k in ("contact", "kontakt"))
+    )
+    contact_url = _resolve_url(contact_nav["url"])
+    print(f"  → contact URL: {contact_url}")
+
+    # Step 2: discover form fields
+    print("Step 2: fetching contact page manifest...")
+    contact = get_action_manifest(contact_url)
+    print(f"  → {len(contact['actions'])} actions, current state: {contact['current_page_state']}")
+
+    # Step 3: plan the fill
+    print("Step 3: planning form fill...")
+    steps = _plan_fill(contact)
+    for s in steps:
+        print(f"  → {s}")
+
+    # Step 4: execute
+    print("Step 4: executing...")
+    _CHROMIUM_PATH = '/usr/bin/chromium-browser'
+    _executable_path = _CHROMIUM_PATH if os.path.exists(_CHROMIUM_PATH) else None
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(
+            headless=_executable_path is not None,
+            executable_path=_executable_path,
+        )
+        _, page = browser_context(browser, start_url=contact_url)
+        page.wait_for_load_state("domcontentloaded")
+        page.wait_for_timeout(2000)
+
+        for step in steps:
+            if step["action"] == "fill":
+                page.get_by_label(step["label"], exact=False).fill(step["value"])
+                page.wait_for_timeout(300)
+            elif step["action"] == "click":
+                page.get_by_role("button", name=step["name"], exact=False).click()
+
+        page.wait_for_timeout(3000)
+        browser.close()
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    fill_contact_form()

manifest_api-0.1.0/example/post_to_linkedin.py

@@ -0,0 +1,33 @@
+import os
+from playwright.sync_api import sync_playwright
+from session import browser_context
+
+COMPOSER_URL = "https://www.linkedin.com/company/113130156/admin/feed/posts?share=true"
+
+def post_to_linkedin(text: str) -> None:
+    _CHROMIUM_PATH = '/usr/bin/chromium-browser'
+    _executable_path = _CHROMIUM_PATH if os.path.exists(_CHROMIUM_PATH) else None
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(
+            headless=_executable_path is not None,
+            executable_path=_executable_path,
+        )
+        context, page = browser_context(browser)
+
+        page.goto(COMPOSER_URL)
+        page.wait_for_selector('[contenteditable="true"]', timeout=15000)
+        page.wait_for_timeout(2000)
+
+        page.locator('[contenteditable="true"]').first.click()
+        page.keyboard.type(text)
+        page.wait_for_timeout(1000)
+
+        page.get_by_role("button", name="Lägg upp", exact=True).click()
+        page.wait_for_timeout(3000)
+
+        browser.close()
+
+if __name__ == "__main__":
+    import sys
+    post_to_linkedin(sys.argv[1] if len(sys.argv) > 1 else "Test post from semantic agent layer.")

manifest_api-0.1.0/manifest.py

@@ -0,0 +1,108 @@
+import json
+import os
+import anthropic
+from dotenv import load_dotenv
+from playwright.sync_api import sync_playwright
+from session import browser_context
+from db import get_cached_manifest, save_manifest
+
+load_dotenv()
+
+_client = anthropic.Anthropic()
+
+_PROMPT = """You are a semantic UI translator for AI agents.
+
+Given the accessibility snapshot of a web page and supplemental DOM context,
+return a JSON action manifest with this structure:
+{{
+  "url": "<page url>",
+  "authenticated_user": "<name or null>",
+  "current_page_state": "<brief description>",
+  "actions": [
+    {{
+      "id": "<slug>",
+      "label": "<human label>",
+      "type": "<input|textarea|select|button|checkbox|radio|other>",
+      "description": "<what it does>",
+      "required": true
+    }}
+  ],
+  "navigation": [
+    {{"label": "<link text>", "url": "<href or null>"}}
+  ]
+}}
+
+Rules:
+- authenticated_user: extract from profile links, greeting text, or avatar labels; null if not detectable
+- actions: only interactive things (buttons, form fields, composers) — skip ads, feed content, footers
+- required: set true if the field appears in dom_context.required_fields (matched by placeholder, name, or label)
+- type: use dom_context.input_types to refine the type (e.g. "email", "tel") when available
+- disabled: omit actions for elements in dom_context.disabled_elements
+- navigation: primary nav links only
+- Return valid JSON only, nothing else
+
+Snapshot:
+{snapshot}
+
+DOM context:
+{dom_context}"""
+
+
+_DOM_EXTRACTORS = {
+    "required_fields": """() => Array.from(document.querySelectorAll("input[required], textarea[required], select[required]"))
+        .map(el => el.placeholder || el.name || el.id)
+        .filter(Boolean)""",
+    "placeholders": """() => Array.from(document.querySelectorAll("input[placeholder], textarea[placeholder]"))
+        .map(el => el.placeholder)
+        .filter(Boolean)""",
+    "disabled_elements": """() => Array.from(document.querySelectorAll("input[disabled], button[disabled], select[disabled], textarea[disabled]"))
+        .map(el => el.placeholder || el.name || el.id || (el.textContent || '').trim())
+        .filter(Boolean)""",
+    "input_types": """() => Array.from(document.querySelectorAll("input"))
+        .map(el => ({ type: el.type, name: el.name || el.id || el.placeholder }))
+        .filter(el => el.name)""",
+}
+
+
+def get_action_manifest(url: str) -> dict:
+    cached = get_cached_manifest(url)
+    if cached is not None:
+        return cached
+
+    _CHROMIUM_PATH = '/usr/bin/chromium-browser'
+    _executable_path = _CHROMIUM_PATH if os.path.exists(_CHROMIUM_PATH) else None
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(
+            headless=_executable_path is not None,
+            executable_path=_executable_path,
+        )
+        context, page = browser_context(browser, start_url=url)
+        page.wait_for_load_state("domcontentloaded")
+        page.wait_for_timeout(2000)
+        snapshot = page.aria_snapshot()
+        dom_context = {key: page.evaluate(js) for key, js in _DOM_EXTRACTORS.items()}
+        browser.close()
+
+    response = _client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=2000,
+        messages=[{"role": "user", "content": _PROMPT.format(
+            snapshot=snapshot,
+            dom_context=json.dumps(dom_context, indent=2),
+        )}],
+    )
+
+    text = response.content[0].text.strip()
+    # strip markdown code fences if model wraps output
+    if text.startswith("```"):
+        text = text.split("\n", 1)[1].rsplit("```", 1)[0]
+    manifest = json.loads(text)
+    manifest["url"] = url
+    save_manifest(url, manifest)
+    return manifest
+
+
+if __name__ == "__main__":
+    import pprint
+    pprint.pprint(get_action_manifest("https://www.linkedin.com/feed/"))

manifest_api-0.1.0/manifest_api/__init__.py

@@ -0,0 +1,28 @@
+"""manifest-api — Python SDK for the Manifest API."""
+
+from .client import (
+    Action,
+    APIError,
+    AsyncManifestClient,
+    AuthenticationError,
+    Manifest,
+    ManifestClient,
+    ManifestError,
+    NavLink,
+    RateLimitError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "ManifestClient",
+    "AsyncManifestClient",
+    "Manifest",
+    "Action",
+    "NavLink",
+    "ManifestError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIError",
+]

manifest_api-0.1.0/manifest_api/client.py

@@ -0,0 +1,237 @@
+"""Manifest API client — sync and async."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import httpx
+
+_BASE_URL = "https://manifest.omfang.io"
+_DEFAULT_TIMEOUT = 30.0
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class ManifestError(Exception):
+    """Base exception for all Manifest API errors."""
+
+
+class AuthenticationError(ManifestError):
+    """Missing or invalid API key."""
+
+
+class RateLimitError(ManifestError):
+    """Rate limit exceeded (429)."""
+
+
+class APIError(ManifestError):
+    """Unexpected API error (5xx or other)."""
+    def __init__(self, message: str, status_code: int) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Action:
+    id: str
+    label: str
+    type: str
+    description: str
+    required: bool
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "Action":
+        return cls(
+            id=d["id"],
+            label=d["label"],
+            type=d["type"],
+            description=d.get("description", ""),
+            required=d.get("required", False),
+        )
+
+
+@dataclass
+class NavLink:
+    label: str
+    url: str
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "NavLink":
+        return cls(label=d["label"], url=d["url"])
+
+
+@dataclass
+class Manifest:
+    url: str
+    authenticated_user: Optional[str]
+    current_page_state: str
+    actions: List[Action] = field(default_factory=list)
+    navigation: List[NavLink] = field(default_factory=list)
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "Manifest":
+        return cls(
+            url=d["url"],
+            authenticated_user=d.get("authenticated_user"),
+            current_page_state=d.get("current_page_state", ""),
+            actions=[Action._from_dict(a) for a in d.get("actions", [])],
+            navigation=[NavLink._from_dict(n) for n in d.get("navigation", [])],
+        )
+
+    def action(self, id: str) -> Optional[Action]:
+        """Return the action with the given id, or None."""
+        return next((a for a in self.actions if a.id == id), None)
+
+    def actions_of_type(self, type: str) -> List[Action]:
+        """Return all actions matching the given type."""
+        return [a for a in self.actions if a.type == type]
+
+    @property
+    def required_actions(self) -> List[Action]:
+        """Return all actions where required=True."""
+        return [a for a in self.actions if a.required]
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("MANIFEST_API_KEY", "")
+    if not key:
+        raise AuthenticationError(
+            "No API key provided. Pass api_key= or set MANIFEST_API_KEY."
+        )
+    return key
+
+
+def _headers(api_key: str) -> dict:
+    return {"X-API-Key": api_key, "Content-Type": "application/json"}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.status_code == 401:
+        raise AuthenticationError("Invalid or missing API key (401).")
+    if response.status_code == 429:
+        raise RateLimitError("Rate limit exceeded (429). Slow down requests.")
+    if response.status_code >= 500:
+        raise APIError(
+            f"Server error: {response.text}", status_code=response.status_code
+        )
+    if response.status_code >= 400:
+        raise APIError(
+            f"Client error {response.status_code}: {response.text}",
+            status_code=response.status_code,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+class ManifestClient:
+    """Synchronous Manifest API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+
+    def get(self, url: str) -> Manifest:
+        """Fetch an action manifest for the given URL."""
+        response = self._client.post(
+            f"{self._base_url}/manifest",
+            json={"url": url},
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return Manifest._from_dict(response.json())
+
+    def health(self) -> dict:
+        """Check API health. Returns the raw JSON response."""
+        response = self._client.get(f"{self._base_url}/health")
+        _raise_for_status(response)
+        return response.json()
+
+    def session_valid(self) -> bool:
+        """Return True if the current session cookie is still valid."""
+        response = self._client.get(
+            f"{self._base_url}/session-status",
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return response.json().get("valid", False)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "ManifestClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class AsyncManifestClient:
+    """Asynchronous Manifest API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def get(self, url: str) -> Manifest:
+        """Fetch an action manifest for the given URL."""
+        response = await self._client.post(
+            f"{self._base_url}/manifest",
+            json={"url": url},
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return Manifest._from_dict(response.json())
+
+    async def health(self) -> dict:
+        """Check API health. Returns the raw JSON response."""
+        response = await self._client.get(f"{self._base_url}/health")
+        _raise_for_status(response)
+        return response.json()
+
+    async def session_valid(self) -> bool:
+        """Return True if the current session cookie is still valid."""
+        response = await self._client.get(
+            f"{self._base_url}/session-status",
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return response.json().get("valid", False)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncManifestClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

manifest_api-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "manifest-api"
+version = "0.1.0"
+description = "Python SDK for the Manifest API — structured action manifests for AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Omfang AB", email = "hello@omfang.io" }]
+keywords = ["ai", "agents", "browser", "automation", "manifest", "web"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "respx>=0.21", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://omfang.io/docs"
+Repository = "https://github.com/omfang/manifest-api"
+"Bug Tracker" = "https://github.com/omfang/manifest-api/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

manifest_api-0.1.0/requirements.txt

@@ -0,0 +1,6 @@
+anthropic==0.112.0
+psycopg2-binary==2.9.10
+playwright==1.60.0
+python-dotenv==1.2.2
+fastapi==0.138.1
+uvicorn==0.49.0

manifest_api-0.1.0/server.py

@@ -0,0 +1,44 @@
+import logging
+import uvicorn
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
+from db import verify_api_key, check_rate_limit, _hash
+from manifest import get_action_manifest
+from session import SessionExpiredError, check_session
+
+logger = logging.getLogger(__name__)
+app = FastAPI()
+
+
+class ManifestRequest(BaseModel):
+    url: str
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.get("/session-status")
+def session_status():
+    if check_session():
+        return {"valid": True}
+    return {"valid": False, "message": "Session expired"}
+
+
+@app.post("/manifest")
+def manifest(req: ManifestRequest, x_api_key: str = Header(default=None)):
+    raw_key = x_api_key or ""
+    if not verify_api_key(raw_key):
+        raise HTTPException(status_code=401, detail="Invalid or missing API key")
+    if not check_rate_limit(_hash(raw_key)):
+        raise HTTPException(status_code=429, detail="Rate limit exceeded. Max 10 requests per minute.")
+    try:
+        return get_action_manifest(req.url)
+    except SessionExpiredError as e:
+        logger.error(str(e))
+        raise HTTPException(status_code=503, detail=str(e))
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

manifest_api-0.1.0/session.py

@@ -0,0 +1,51 @@
+import os
+from playwright.sync_api import sync_playwright
+
+SESSION_FILE = "session.json"
+_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+_CHROMIUM_PATH = "/usr/bin/chromium-browser"
+
+
+class SessionExpiredError(RuntimeError):
+    pass
+
+
+def browser_context(browser, start_url="https://www.linkedin.com/feed/"):
+    """Return (context, page) navigated to start_url, prompting for login if needed."""
+    has_session = os.path.exists(SESSION_FILE)
+    kwargs = {"user_agent": _UA}
+    if has_session:
+        kwargs["storage_state"] = SESSION_FILE
+
+    context = browser.new_context(**kwargs)
+    page = context.new_page()
+    page.goto(start_url)
+
+    if not has_session:
+        raise RuntimeError(
+            f"No session file found at '{SESSION_FILE}'. "
+            "Run locally first to log in and generate the session file."
+        )
+
+    if "login" in page.url or "authwall" in page.url:
+        raise SessionExpiredError(
+            "Session expired — refresh session.json by running session.py locally and re-uploading to the server"
+        )
+
+    return context, page
+
+
+def check_session() -> bool:
+    """Return True if session.json exists and is still valid on LinkedIn."""
+    if not os.path.exists(SESSION_FILE):
+        return False
+    executable_path = _CHROMIUM_PATH if os.path.exists(_CHROMIUM_PATH) else None
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=executable_path is not None, executable_path=executable_path)
+        try:
+            browser_context(browser)
+            return True
+        except SessionExpiredError:
+            return False
+        finally:
+            browser.close()

manifest_api-0.1.0/tests/test_client.py

@@ -0,0 +1,144 @@
+"""Tests for manifest_api client."""
+
+import os
+import pytest
+import respx
+import httpx
+
+from manifest_api import (
+    ManifestClient,
+    AsyncManifestClient,
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+
+BASE = "https://manifest.omfang.io"
+
+MANIFEST_PAYLOAD = {
+    "url": "https://example.com",
+    "authenticated_user": None,
+    "current_page_state": "Landing page",
+    "actions": [
+        {
+            "id": "submit-form",
+            "label": "Submit",
+            "type": "button",
+            "description": "Submits the contact form",
+            "required": False,
+        },
+        {
+            "id": "email-input",
+            "label": "Email",
+            "type": "input",
+            "description": "Email address field",
+            "required": True,
+        },
+    ],
+    "navigation": [{"label": "Home", "url": "/"}],
+}
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+@respx.mock
+def test_successful_manifest_fetch():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(200, json=MANIFEST_PAYLOAD))
+
+    client = ManifestClient(api_key="test-key")
+    manifest = client.get("https://example.com")
+
+    assert manifest.url == "https://example.com"
+    assert manifest.current_page_state == "Landing page"
+    assert len(manifest.actions) == 2
+    assert len(manifest.navigation) == 1
+
+
+def test_missing_api_key_raises_authentication_error(monkeypatch):
+    monkeypatch.delenv("MANIFEST_API_KEY", raising=False)
+    with pytest.raises(AuthenticationError):
+        ManifestClient()
+
+
+@respx.mock
+def test_401_raises_authentication_error():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(401))
+
+    client = ManifestClient(api_key="bad-key")
+    with pytest.raises(AuthenticationError):
+        client.get("https://example.com")
+
+
+@respx.mock
+def test_429_raises_rate_limit_error():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(429))
+
+    client = ManifestClient(api_key="test-key")
+    with pytest.raises(RateLimitError):
+        client.get("https://example.com")
+
+
+@respx.mock
+def test_500_raises_api_error():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(500, text="oops"))
+
+    client = ManifestClient(api_key="test-key")
+    with pytest.raises(APIError) as exc_info:
+        client.get("https://example.com")
+    assert exc_info.value.status_code == 500
+
+
+@respx.mock
+def test_action_lookup():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(200, json=MANIFEST_PAYLOAD))
+
+    client = ManifestClient(api_key="test-key")
+    manifest = client.get("https://example.com")
+
+    action = manifest.action("submit-form")
+    assert action is not None
+    assert action.label == "Submit"
+    assert manifest.action("nonexistent") is None
+
+
+@respx.mock
+def test_required_actions_filter():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(200, json=MANIFEST_PAYLOAD))
+
+    client = ManifestClient(api_key="test-key")
+    manifest = client.get("https://example.com")
+
+    required = manifest.required_actions
+    assert len(required) == 1
+    assert required[0].id == "email-input"
+
+
+@respx.mock
+def test_actions_of_type():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(200, json=MANIFEST_PAYLOAD))
+
+    client = ManifestClient(api_key="test-key")
+    manifest = client.get("https://example.com")
+
+    buttons = manifest.actions_of_type("button")
+    assert len(buttons) == 1
+    assert buttons[0].id == "submit-form"
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+@respx.mock
+async def test_async_client_happy_path():
+    respx.post(f"{BASE}/manifest").mock(return_value=httpx.Response(200, json=MANIFEST_PAYLOAD))
+
+    async with AsyncManifestClient(api_key="test-key") as client:
+        manifest = await client.get("https://example.com")
+
+    assert manifest.url == "https://example.com"
+    assert len(manifest.actions) == 2
+    assert manifest.action("submit-form") is not None
+    assert manifest.required_actions[0].id == "email-input"