agentberlin 0.9.0__py3-none-any.whl

agentberlin/__init__.py

@@ -0,0 +1,51 @@
+"""Agent Berlin Python SDK.
+
+A Python SDK for Agent Berlin - AI-powered SEO and AEO automation.
+
+Example:
+    from agentberlin import AgentBerlin
+
+    # Set AGENTBERLIN_TOKEN environment variable or pass token directly
+    client = AgentBerlin()
+
+    # Get analytics
+    analytics = client.analytics.get(project_domain="example.com")
+
+    # Search pages
+    pages = client.pages.search(project_domain="example.com", query="SEO tips")
+
+    # Search keywords
+    keywords = client.keywords.search(project_domain="example.com", query="marketing")
+
+    # Get brand profile
+    profile = client.brand.get_profile(project_domain="example.com")
+
+    # Fetch SERP results
+    serp = client.serp.fetch(query="best seo tools")
+"""
+
+from .client import AgentBerlin
+from .exceptions import (
+    AgentBerlinAPIError,
+    AgentBerlinAuthenticationError,
+    AgentBerlinConnectionError,
+    AgentBerlinError,
+    AgentBerlinNotFoundError,
+    AgentBerlinRateLimitError,
+    AgentBerlinServerError,
+    AgentBerlinValidationError,
+)
+
+__version__ = "0.9.0"
+
+__all__ = [
+    "AgentBerlin",
+    "AgentBerlinError",
+    "AgentBerlinAuthenticationError",
+    "AgentBerlinAPIError",
+    "AgentBerlinNotFoundError",
+    "AgentBerlinRateLimitError",
+    "AgentBerlinServerError",
+    "AgentBerlinValidationError",
+    "AgentBerlinConnectionError",
+]

agentberlin/_http.py

@@ -0,0 +1,193 @@
+"""Internal HTTP client for Agent Berlin SDK."""
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .exceptions import (
+    AgentBerlinAPIError,
+    AgentBerlinAuthenticationError,
+    AgentBerlinConnectionError,
+    AgentBerlinNotFoundError,
+    AgentBerlinRateLimitError,
+    AgentBerlinServerError,
+)
+
+__version__ = "0.1.0"
+
+
+class HTTPClient:
+    """Internal HTTP client with authentication and error handling."""
+
+    def __init__(
+        self,
+        token: str,
+        base_url: str,
+        timeout: int = 30,
+    ) -> None:
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "User-Agent": f"agentberlin-python/{__version__}",
+            }
+        )
+
+    def post(
+        self,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a POST request.
+
+        Args:
+            path: API endpoint path.
+            json: Request body as dict.
+
+        Returns:
+            Response data as dict.
+
+        Raises:
+            AgentBerlinAPIError: On API errors.
+            AgentBerlinConnectionError: On network errors.
+        """
+        url = f"{self._base_url}{path}"
+
+        try:
+            response = self._session.post(
+                url,
+                json=json,
+                timeout=self._timeout,
+            )
+        except requests.exceptions.Timeout:
+            raise AgentBerlinConnectionError(f"Request timed out after {self._timeout}s")
+        except requests.exceptions.ConnectionError as e:
+            raise AgentBerlinConnectionError(f"Connection error: {e}")
+        except requests.exceptions.RequestException as e:
+            raise AgentBerlinConnectionError(f"Request failed: {e}")
+
+        return self._handle_response(response)
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a GET request.
+
+        Args:
+            path: API endpoint path.
+            params: Query parameters.
+
+        Returns:
+            Response data as dict.
+
+        Raises:
+            AgentBerlinAPIError: On API errors.
+            AgentBerlinConnectionError: On network errors.
+        """
+        url = f"{self._base_url}{path}"
+
+        try:
+            response = self._session.get(
+                url,
+                params=params,
+                timeout=self._timeout,
+            )
+        except requests.exceptions.Timeout:
+            raise AgentBerlinConnectionError(f"Request timed out after {self._timeout}s")
+        except requests.exceptions.ConnectionError as e:
+            raise AgentBerlinConnectionError(f"Connection error: {e}")
+        except requests.exceptions.RequestException as e:
+            raise AgentBerlinConnectionError(f"Request failed: {e}")
+
+        return self._handle_response(response)
+
+    def patch(
+        self,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a PATCH request.
+
+        Args:
+            path: API endpoint path.
+            json: Request body as dict.
+
+        Returns:
+            Response data as dict.
+
+        Raises:
+            AgentBerlinAPIError: On API errors.
+            AgentBerlinConnectionError: On network errors.
+        """
+        url = f"{self._base_url}{path}"
+
+        try:
+            response = self._session.patch(
+                url,
+                json=json,
+                timeout=self._timeout,
+            )
+        except requests.exceptions.Timeout:
+            raise AgentBerlinConnectionError(f"Request timed out after {self._timeout}s")
+        except requests.exceptions.ConnectionError as e:
+            raise AgentBerlinConnectionError(f"Connection error: {e}")
+        except requests.exceptions.RequestException as e:
+            raise AgentBerlinConnectionError(f"Request failed: {e}")
+
+        return self._handle_response(response)
+
+    def _handle_response(self, response: requests.Response) -> Dict[str, Any]:
+        """Handle response and raise appropriate exceptions."""
+        # Success
+        if response.ok:
+            if response.content:
+                return response.json()  # type: ignore[no-any-return]
+            return {}
+
+        # Parse error response
+        try:
+            error_data = response.json()
+            message = error_data.get("message", error_data.get("error", "Unknown error"))
+            error_code = error_data.get("code")
+        except Exception:
+            message = response.text or f"HTTP {response.status_code}"
+            error_code = None
+            error_data = {}
+
+        # Map status codes to exceptions
+        if response.status_code == 401:
+            raise AgentBerlinAuthenticationError(message, details=error_data)
+        elif response.status_code == 404:
+            raise AgentBerlinNotFoundError(
+                message,
+                status_code=404,
+                error_code=error_code,
+                details=error_data,
+            )
+        elif response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise AgentBerlinRateLimitError(
+                message,
+                retry_after=int(retry_after) if retry_after else None,
+                details=error_data,
+            )
+        elif response.status_code >= 500:
+            raise AgentBerlinServerError(
+                message,
+                status_code=response.status_code,
+                error_code=error_code,
+                details=error_data,
+            )
+        else:
+            raise AgentBerlinAPIError(
+                message,
+                status_code=response.status_code,
+                error_code=error_code,
+                details=error_data,
+            )

agentberlin/client.py

@@ -0,0 +1,85 @@
+"""Main client class for Agent Berlin SDK.
+
+Example:
+    from agentberlin import AgentBerlin
+
+    client = AgentBerlin()  # Uses AGENTBERLIN_TOKEN env var
+
+    # Get analytics
+    analytics = client.analytics.get(project_domain="example.com")
+    print(f"Traffic: {analytics.traffic.total_sessions}")
+
+    # Search pages
+    pages = client.pages.search(project_domain="example.com", query="SEO tips")
+    for page in pages.pages:
+        print(f"  - {page.title}: {page.url}")
+"""
+
+import os
+from typing import Optional
+
+from ._http import HTTPClient
+from .config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, Config
+from .exceptions import AgentBerlinAuthenticationError
+from .resources.analytics import AnalyticsResource
+from .resources.brand import BrandResource
+from .resources.keywords import KeywordsResource
+from .resources.pages import PagesResource
+from .resources.serp import SERPResource
+
+
+class AgentBerlin:
+    """Client for the Agent Berlin API.
+
+    Args:
+        token: API token. If not provided, reads from AGENTBERLIN_TOKEN env var.
+        base_url: Base URL for the API. Defaults to https://backend.agentberlin.ai/sdk
+        timeout: Request timeout in seconds. Defaults to 30.
+
+    Raises:
+        AgentBerlinAuthenticationError: If no token is provided or found in env.
+
+    Attributes:
+        analytics: Analytics resource for fetching analytics data.
+        pages: Pages resource for searching and getting page details.
+        keywords: Keywords resource for semantic keyword search.
+        brand: Brand resource for managing brand profiles.
+        serp: SERP resource for fetching Google search results.
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> None:
+        # Get token from parameter or environment
+        self._token = token or os.environ.get("AGENTBERLIN_TOKEN")
+        if not self._token:
+            raise AgentBerlinAuthenticationError(
+                "No API token provided. Set AGENTBERLIN_TOKEN environment variable "
+                "or pass token parameter to AgentBerlin()."
+            )
+
+        # Initialize config
+        self._config = Config(
+            base_url=base_url or DEFAULT_BASE_URL,
+            timeout=timeout,
+        )
+
+        # Initialize HTTP client
+        self._http = HTTPClient(
+            token=self._token,
+            base_url=self._config.base_url,
+            timeout=self._config.timeout,
+        )
+
+        # Initialize resources
+        self.analytics = AnalyticsResource(self._http)
+        self.pages = PagesResource(self._http)
+        self.keywords = KeywordsResource(self._http)
+        self.brand = BrandResource(self._http)
+        self.serp = SERPResource(self._http)
+
+    def __repr__(self) -> str:
+        return f"AgentBerlin(base_url='{self._config.base_url}')"

agentberlin/config.py

@@ -0,0 +1,19 @@
+"""Configuration for the Agent Berlin SDK."""
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://backend.agentberlin.ai/sdk"
+DEFAULT_TIMEOUT = 30
+
+
+@dataclass
+class Config:
+    """SDK configuration.
+
+    Attributes:
+        base_url: Base URL for the Agent Berlin API.
+        timeout: Request timeout in seconds.
+    """
+
+    base_url: str = DEFAULT_BASE_URL
+    timeout: int = DEFAULT_TIMEOUT

agentberlin/exceptions.py

@@ -0,0 +1,88 @@
+"""Custom exceptions for the Agent Berlin SDK.
+
+Exception hierarchy:
+    AgentBerlinError (base)
+    ├── AgentBerlinAuthenticationError  - Token missing or invalid
+    ├── AgentBerlinAPIError             - API returned an error
+    │   ├── AgentBerlinNotFoundError    - Resource not found (404)
+    │   ├── AgentBerlinRateLimitError   - Rate limit exceeded (429)
+    │   └── AgentBerlinServerError      - Server error (5xx)
+    ├── AgentBerlinValidationError      - Invalid parameters
+    └── AgentBerlinConnectionError      - Network/connection issues
+"""
+
+from typing import Any, Dict, Optional
+
+
+class AgentBerlinError(Exception):
+    """Base exception for all Agent Berlin SDK errors."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class AgentBerlinAuthenticationError(AgentBerlinError):
+    """Raised when authentication fails or token is missing."""
+
+    pass
+
+
+class AgentBerlinAPIError(AgentBerlinError):
+    """Raised when the API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        error_code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, details)
+        self.status_code = status_code
+        self.error_code = error_code
+
+
+class AgentBerlinNotFoundError(AgentBerlinAPIError):
+    """Raised when a requested resource is not found (404)."""
+
+    pass
+
+
+class AgentBerlinRateLimitError(AgentBerlinAPIError):
+    """Raised when rate limit is exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, status_code=429, details=details)
+        self.retry_after = retry_after
+
+
+class AgentBerlinServerError(AgentBerlinAPIError):
+    """Raised when the server returns a 5xx error."""
+
+    pass
+
+
+class AgentBerlinValidationError(AgentBerlinError):
+    """Raised when request parameters fail validation."""
+
+    def __init__(
+        self,
+        message: str,
+        field: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, details)
+        self.field = field
+
+
+class AgentBerlinConnectionError(AgentBerlinError):
+    """Raised when there's a network or connection error."""
+
+    pass

agentberlin/models/__init__.py

@@ -0,0 +1,53 @@
+"""Pydantic models for Agent Berlin API responses."""
+
+from .analytics import (
+    AnalyticsResponse,
+    ChannelBreakdown,
+    CompetitorSummary,
+    DailyTraffic,
+    DataRange,
+    TopicSummary,
+    TrafficData,
+    VisibilityData,
+    VisibilityPoint,
+)
+from .brand import BrandProfileResponse, BrandProfileUpdateResponse
+from .search import (
+    KeywordResult,
+    KeywordSearchResponse,
+    PageDetailResponse,
+    PageLink,
+    PageLinksDetail,
+    PageResult,
+    PageSearchResponse,
+    PageTopicInfo,
+)
+from .serp import SERPResponse, SERPResult
+
+__all__ = [
+    # Analytics
+    "AnalyticsResponse",
+    "VisibilityData",
+    "VisibilityPoint",
+    "TrafficData",
+    "ChannelBreakdown",
+    "DailyTraffic",
+    "TopicSummary",
+    "CompetitorSummary",
+    "DataRange",
+    # Search
+    "PageSearchResponse",
+    "PageResult",
+    "KeywordSearchResponse",
+    "KeywordResult",
+    "PageDetailResponse",
+    "PageLinksDetail",
+    "PageLink",
+    "PageTopicInfo",
+    # Brand
+    "BrandProfileResponse",
+    "BrandProfileUpdateResponse",
+    # SERP
+    "SERPResponse",
+    "SERPResult",
+]

agentberlin/models/analytics.py

@@ -0,0 +1,87 @@
+"""Pydantic models for analytics API responses."""
+
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class VisibilityPoint(BaseModel):
+    """Single point in visibility history."""
+
+    date: str
+    percentage: float
+
+
+class VisibilityData(BaseModel):
+    """Visibility metrics for a domain."""
+
+    current_percentage: float
+    ranking_stability: float
+    share_of_voice: float
+    history: List[VisibilityPoint] = Field(default_factory=list)
+
+
+class ChannelBreakdown(BaseModel):
+    """Traffic breakdown by channel."""
+
+    direct: int = 0
+    organic_search: int = 0
+    referral: int = 0
+    organic_social: int = 0
+    llm: int = 0
+    other: int = 0
+
+
+class DailyTraffic(BaseModel):
+    """Daily traffic data point."""
+
+    date: str
+    sessions: int
+    llm_sessions: int
+
+
+class TrafficData(BaseModel):
+    """Traffic metrics for a domain."""
+
+    total_sessions: int
+    llm_sessions: int
+    channel_breakdown: ChannelBreakdown
+    daily_trend: List[DailyTraffic] = Field(default_factory=list)
+
+
+class TopicSummary(BaseModel):
+    """Summary of a topic's performance."""
+
+    name: str
+    appearances: int
+    avg_position: float
+    topical_authority: float
+    trend: str  # "up", "down", "stable"
+
+
+class CompetitorSummary(BaseModel):
+    """Summary of competitor visibility."""
+
+    name: str
+    visibility: float
+    share_of_voice: float
+
+
+class DataRange(BaseModel):
+    """Date range for the analytics data."""
+
+    start: str
+    end: str
+
+
+class AnalyticsResponse(BaseModel):
+    """Complete analytics response for a domain."""
+
+    domain: str
+    domain_authority: int
+    visibility: VisibilityData
+    traffic: TrafficData
+    topics: List[TopicSummary] = Field(default_factory=list)
+    competitors: List[CompetitorSummary] = Field(default_factory=list)
+    data_range: DataRange
+    last_updated: str

agentberlin/models/brand.py

@@ -0,0 +1,40 @@
+"""Pydantic models for brand profile API responses."""
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class BrandProfileResponse(BaseModel):
+    """Brand profile configuration for a project."""
+
+    domain: str
+    name: str
+    context: str
+    search_analysis_context: Optional[str] = None
+    domain_authority: int
+    competitors: List[str] = Field(default_factory=list)
+    industries: List[str] = Field(default_factory=list)
+    business_models: List[str] = Field(default_factory=list)
+    company_size: str
+    target_customer_segments: List[str] = Field(default_factory=list)
+    geographies: List[str] = Field(default_factory=list)
+    personas: List[str] = Field(default_factory=list)
+    sitemaps: List[str] = Field(default_factory=list)
+    profile_urls: List[str] = Field(default_factory=list)
+
+
+class BrandProfileUpdateField(BaseModel):
+    """Updated field information."""
+
+    field: str
+    value: Any
+
+
+class BrandProfileUpdateResponse(BaseModel):
+    """Response for brand profile update."""
+
+    success: bool
+    domain: str
+    mode: str
+    updated: BrandProfileUpdateField

agentberlin/models/search.py

@@ -0,0 +1,85 @@
+"""Pydantic models for search API responses (pages, keywords)."""
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+# Page search models
+
+
+class PageResult(BaseModel):
+    """Single page in search results."""
+
+    url: str
+    title: str
+
+
+class PageSearchResponse(BaseModel):
+    """Response for page search."""
+
+    pages: List[PageResult] = Field(default_factory=list)
+    total: int
+
+
+# Keyword search models
+
+
+class KeywordResult(BaseModel):
+    """Single keyword with metadata."""
+
+    keyword: str
+    volume: Optional[int] = None
+    difficulty: Optional[int] = None  # 0-100
+    cpc: Optional[float] = None
+    intent: Optional[str] = None  # informational, commercial, transactional, navigational
+
+
+class KeywordSearchResponse(BaseModel):
+    """Response for keyword search."""
+
+    keywords: List[KeywordResult] = Field(default_factory=list)
+    total: int
+
+
+# Get page models
+
+
+class PageLink(BaseModel):
+    """Link in page details."""
+
+    source_url: str
+    target_url: str
+    anchor_text: Optional[str] = None
+    domain_type: str  # "internal" or "external"
+    source_title: Optional[str] = None
+    target_title: Optional[str] = None
+
+
+class PageLinksDetail(BaseModel):
+    """Links for a page."""
+
+    inlinks: List[PageLink] = Field(default_factory=list)
+    outlinks: List[PageLink] = Field(default_factory=list)
+
+
+class PageTopicInfo(BaseModel):
+    """Topic classification for a page."""
+
+    topics: List[str] = Field(default_factory=list)
+    topic_scores: List[float] = Field(default_factory=list)
+    page_type: Optional[str] = None  # "pillar" or "landing"
+    assigned_topic: Optional[str] = None
+
+
+class PageDetailResponse(BaseModel):
+    """Detailed page information."""
+
+    url: str
+    title: Optional[str] = None
+    meta_description: Optional[str] = None
+    h1: Optional[str] = None
+    domain: Optional[str] = None
+    links: Optional[PageLinksDetail] = None
+    topic_info: Optional[PageTopicInfo] = None
+    content_preview: Optional[str] = None
+    content_length: int = 0

agentberlin/models/serp.py

@@ -0,0 +1,21 @@
+"""Pydantic models for SERP API responses."""
+
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class SERPResult(BaseModel):
+    """Single search result."""
+
+    title: str
+    url: str
+    snippet: str
+
+
+class SERPResponse(BaseModel):
+    """Response for SERP fetch."""
+
+    query: str
+    results: List[SERPResult] = Field(default_factory=list)
+    total: int

agentberlin/resources/__init__.py

@@ -0,0 +1,15 @@
+"""Resource classes for Agent Berlin SDK."""
+
+from .analytics import AnalyticsResource
+from .brand import BrandResource
+from .keywords import KeywordsResource
+from .pages import PagesResource
+from .serp import SERPResource
+
+__all__ = [
+    "AnalyticsResource",
+    "PagesResource",
+    "KeywordsResource",
+    "BrandResource",
+    "SERPResource",
+]

agentberlin/resources/analytics.py

@@ -0,0 +1,40 @@
+"""Analytics resource for Agent Berlin SDK."""
+
+from .._http import HTTPClient
+from ..models.analytics import AnalyticsResponse
+
+
+class AnalyticsResource:
+    """Resource for analytics operations.
+
+    Example:
+        analytics = client.analytics.get(project_domain="example.com")
+        print(f"Visibility: {analytics.visibility.current_percentage}%")
+        print(f"LLM Sessions: {analytics.traffic.llm_sessions}")
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def get(self, project_domain: str) -> AnalyticsResponse:
+        """Get analytics data for a project.
+
+        Fetch analytics dashboard data including visibility, traffic,
+        topics, and competitors.
+
+        Args:
+            project_domain: The domain of the project (e.g., 'example.com').
+
+        Returns:
+            AnalyticsResponse with comprehensive analytics data.
+
+        Raises:
+            AgentBerlinValidationError: If project_domain is empty.
+            AgentBerlinNotFoundError: If the domain doesn't exist.
+            AgentBerlinAPIError: If the API returns an error.
+        """
+        data = self._http.post(
+            "/analytics",
+            json={"project_domain": project_domain},
+        )
+        return AnalyticsResponse.model_validate(data)

agentberlin/resources/brand.py

@@ -0,0 +1,88 @@
+"""Brand resource for Agent Berlin SDK."""
+
+from typing import Literal, Optional
+
+from .._http import HTTPClient
+from ..models.brand import BrandProfileResponse, BrandProfileUpdateResponse
+
+
+class BrandResource:
+    """Resource for brand profile operations.
+
+    Example:
+        # Get brand profile
+        profile = client.brand.get_profile(project_domain="example.com")
+        print(f"Domain Authority: {profile.domain_authority}")
+        print(f"Competitors: {profile.competitors}")
+
+        # Update brand profile
+        client.brand.update_profile(
+            project_domain="example.com",
+            field="competitors",
+            value="competitor.com",
+            mode="add"
+        )
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def get_profile(self, project_domain: str) -> BrandProfileResponse:
+        """Get the brand profile configuration for a project.
+
+        Args:
+            project_domain: The domain of the project (e.g., 'example.com').
+
+        Returns:
+            BrandProfileResponse with brand configuration.
+        """
+        data = self._http.post(
+            "/brand/profile",
+            json={"project_domain": project_domain},
+        )
+        return BrandProfileResponse.model_validate(data)
+
+    def update_profile(
+        self,
+        project_domain: str,
+        field: Literal[
+            "name",
+            "context",
+            "competitors",
+            "industries",
+            "business_models",
+            "company_size",
+            "target_segments",
+            "geographies",
+            "personas",
+        ],
+        value: str,
+        *,
+        mode: Literal["add", "set"] = "add",
+    ) -> BrandProfileUpdateResponse:
+        """Update a specific field in the brand profile.
+
+        For array fields (competitors, industries, etc.), you can either
+        add new values to existing ones or set (replace) all values.
+
+        Args:
+            project_domain: The domain of the project (e.g., 'example.com').
+            field: The field to update.
+            value: The new value. For array fields, provide comma-separated values.
+            mode: For array fields: 'add' adds to existing, 'set' replaces all.
+
+        Returns:
+            BrandProfileUpdateResponse with update confirmation.
+
+        Note:
+            Valid company_size values: solo, early_startup, startup, smb, mid_market, enterprise
+        """
+        payload: dict[str, object] = {
+            "project_domain": project_domain,
+            "field": field,
+            "value": value,
+            "mode": mode,
+        }
+
+        data = self._http.post("/brand/profile/update", json=payload)
+        return BrandProfileUpdateResponse.model_validate(data)

agentberlin/resources/keywords.py

@@ -0,0 +1,53 @@
+"""Keywords resource for Agent Berlin SDK."""
+
+from typing import Optional
+
+from .._http import HTTPClient
+from ..models.search import KeywordSearchResponse
+
+
+class KeywordsResource:
+    """Resource for keyword operations.
+
+    Example:
+        results = client.keywords.search(
+            project_domain="example.com",
+            query="digital marketing",
+            limit=20
+        )
+        for kw in results.keywords:
+            print(f"{kw.keyword}: volume={kw.volume}, difficulty={kw.difficulty}")
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def search(
+        self,
+        project_domain: str,
+        query: str,
+        *,
+        limit: Optional[int] = None,
+    ) -> KeywordSearchResponse:
+        """Search for keywords by semantic query.
+
+        Returns relevant keywords with metadata including search volume,
+        difficulty, CPC, and intent classification.
+
+        Args:
+            project_domain: Your project's domain (e.g., 'example.com').
+            query: Search query for semantic matching.
+            limit: Maximum results (default: 10, max: 50).
+
+        Returns:
+            KeywordSearchResponse with matching keywords and metadata.
+        """
+        payload: dict[str, object] = {
+            "project_domain": project_domain,
+            "query": query,
+        }
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = self._http.post("/keywords/search", json=payload)
+        return KeywordSearchResponse.model_validate(data)

agentberlin/resources/pages.py

@@ -0,0 +1,100 @@
+"""Pages resource for Agent Berlin SDK."""
+
+from typing import Optional
+
+from .._http import HTTPClient
+from ..models.search import PageDetailResponse, PageSearchResponse
+
+
+class PagesResource:
+    """Resource for page operations.
+
+    Example:
+        # Search for pages
+        results = client.pages.search(
+            project_domain="example.com",
+            query="SEO best practices",
+            limit=20
+        )
+
+        # Get page details
+        page = client.pages.get(
+            project_domain="example.com",
+            url="https://example.com/blog/seo-tips"
+        )
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def search(
+        self,
+        project_domain: str,
+        query: str,
+        *,
+        domain: Optional[str] = None,
+        limit: Optional[int] = None,
+        status_code: Optional[str] = None,
+        topic: Optional[str] = None,
+        page_type: Optional[str] = None,
+    ) -> PageSearchResponse:
+        """Search for pages by semantic query.
+
+        Can search your brand's pages, competitor pages, or all indexed pages.
+
+        Args:
+            project_domain: Your project's domain (e.g., 'example.com').
+            query: Search query for semantic matching.
+            domain: Optional filter to a specific domain.
+            limit: Maximum results (default: 10, max: 50).
+            status_code: Filter by HTTP status ('200', '404', 'error', 'redirect', 'success').
+            topic: Filter by topic name.
+            page_type: Filter by page type ('pillar' or 'landing').
+
+        Returns:
+            PageSearchResponse with matching pages.
+        """
+        payload: dict[str, object] = {
+            "project_domain": project_domain,
+            "query": query,
+        }
+        if domain is not None:
+            payload["domain"] = domain
+        if limit is not None:
+            payload["limit"] = limit
+        if status_code is not None:
+            payload["status_code"] = status_code
+        if topic is not None:
+            payload["topic"] = topic
+        if page_type is not None:
+            payload["page_type"] = page_type
+
+        data = self._http.post("/pages/search", json=payload)
+        return PageSearchResponse.model_validate(data)
+
+    def get(
+        self,
+        project_domain: str,
+        url: str,
+        *,
+        content_length: Optional[int] = None,
+    ) -> PageDetailResponse:
+        """Get detailed information about a specific page.
+
+        Args:
+            project_domain: Your project's domain (e.g., 'example.com').
+            url: The page URL to look up.
+            content_length: Max characters of content to return (default: 0).
+
+        Returns:
+            PageDetailResponse with page metadata, links, and topic info.
+        """
+        payload: dict[str, object] = {
+            "project_domain": project_domain,
+            "url": url,
+        }
+        if content_length is not None:
+            payload["content_length"] = content_length
+
+        data = self._http.post("/pages/get", json=payload)
+        return PageDetailResponse.model_validate(data)

agentberlin/resources/serp.py

@@ -0,0 +1,57 @@
+"""SERP resource for Agent Berlin SDK."""
+
+from typing import Optional
+
+from .._http import HTTPClient
+from ..models.serp import SERPResponse
+
+
+class SERPResource:
+    """Resource for SERP (Search Engine Results Page) operations.
+
+    Example:
+        results = client.serp.fetch(
+            query="best seo tools",
+            max_results=5,
+            country="us",
+            language="lang_en"
+        )
+        for result in results.results:
+            print(f"{result.title}: {result.url}")
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def fetch(
+        self,
+        query: str,
+        *,
+        max_results: Optional[int] = None,
+        country: Optional[str] = None,
+        language: Optional[str] = None,
+    ) -> SERPResponse:
+        """Fetch Google SERP data for a query.
+
+        Returns titles, URLs, and snippets of top-ranking pages.
+
+        Args:
+            query: The search query to execute.
+            max_results: Number of results (1-10, default: 10).
+            country: ISO 3166-1 alpha-2 country code (e.g., 'us', 'gb', 'de').
+            language: ISO 639-1 language code prefixed with 'lang_'
+                     (e.g., 'lang_en', 'lang_de', 'lang_fr').
+
+        Returns:
+            SERPResponse with search results.
+        """
+        payload: dict[str, object] = {"query": query}
+        if max_results is not None:
+            payload["max_results"] = max_results
+        if country is not None:
+            payload["country"] = country
+        if language is not None:
+            payload["language"] = language
+
+        data = self._http.post("/serp/fetch", json=payload)
+        return SERPResponse.model_validate(data)

agentberlin-0.9.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: agentberlin
+Version: 0.9.0
+Summary: Python SDK for Agent Berlin - AI-powered SEO and AEO automation
+Project-URL: Homepage, https://agentberlin.ai
+Project-URL: Documentation, https://docs.agentberlin.ai/sdk/python
+Project-URL: Repository, https://github.com/boat-builder/berlin
+Author-email: Agent Berlin <support@agentberlin.ai>
+License: MIT
+License-File: LICENSE
+Keywords: aeo,ai,analytics,optimization,search,seo
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: responses>=0.25.0; extra == 'dev'
+Requires-Dist: types-requests>=2.31.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agent Berlin Python SDK
+
+Official Python SDK for [Agent Berlin](https://agentberlin.ai) - AI-powered SEO and AEO automation.
+
+## Installation
+
+```bash
+pip install agentberlin
+```
+
+## Quick Start
+
+```python
+from agentberlin import AgentBerlin
+
+# Set your API token as an environment variable
+# export AGENTBERLIN_TOKEN="your-token-here"
+
+client = AgentBerlin()
+
+# Get analytics for your project
+analytics = client.analytics.get(project_domain="example.com")
+print(f"Visibility: {analytics.visibility.current_percentage}%")
+print(f"LLM Sessions: {analytics.traffic.llm_sessions}")
+
+# Search for pages
+pages = client.pages.search(
+    project_domain="example.com",
+    query="SEO best practices",
+    limit=10
+)
+for page in pages.pages:
+    print(f"  - {page.title}: {page.url}")
+
+# Search for keywords
+keywords = client.keywords.search(
+    project_domain="example.com",
+    query="digital marketing"
+)
+for kw in keywords.keywords:
+    print(f"  - {kw.keyword} (volume: {kw.volume})")
+
+# Get page details
+page = client.pages.get(
+    project_domain="example.com",
+    url="https://example.com/blog/seo-tips"
+)
+print(f"Title: {page.title}")
+print(f"H1: {page.h1}")
+
+# Get brand profile
+profile = client.brand.get_profile(project_domain="example.com")
+print(f"Domain Authority: {profile.domain_authority}")
+
+# Update brand profile
+client.brand.update_profile(
+    project_domain="example.com",
+    field="competitors",
+    value="competitor.com",
+    mode="add"
+)
+
+# Fetch SERP results
+serp = client.serp.fetch(query="best seo tools", max_results=5)
+for result in serp.results:
+    print(f"  - {result.title}: {result.url}")
+```
+
+## Authentication
+
+The SDK requires an API token. Set it as an environment variable:
+
+```bash
+export AGENTBERLIN_TOKEN="your-token-here"
+```
+
+Or pass it directly:
+
+```python
+client = AgentBerlin(token="your-token-here")
+```
+
+## Configuration
+
+```python
+client = AgentBerlin(
+    token="your-token",           # Optional if AGENTBERLIN_TOKEN env var is set
+    base_url="https://...",       # Optional, defaults to production API
+    timeout=30,                   # Request timeout in seconds
+)
+```
+
+## Resources
+
+### Analytics
+```python
+client.analytics.get(project_domain="example.com")
+```
+
+### Pages
+```python
+client.pages.search(project_domain, query, domain=None, limit=10, status_code=None, topic=None, page_type=None)
+client.pages.get(project_domain, url, content_length=0)
+```
+
+### Keywords
+```python
+client.keywords.search(project_domain, query, limit=10)
+```
+
+### Brand
+```python
+client.brand.get_profile(project_domain)
+client.brand.update_profile(project_domain, field, value, mode="add")
+```
+
+### SERP
+```python
+client.serp.fetch(query, max_results=10, country=None, language=None)
+```
+
+## Error Handling
+
+```python
+from agentberlin import AgentBerlin
+from agentberlin.exceptions import (
+    AgentBerlinError,
+    AgentBerlinAuthenticationError,
+    AgentBerlinNotFoundError,
+    AgentBerlinRateLimitError,
+)
+
+client = AgentBerlin()
+
+try:
+    analytics = client.analytics.get(project_domain="example.com")
+except AgentBerlinAuthenticationError:
+    print("Invalid or missing API token")
+except AgentBerlinNotFoundError:
+    print("Domain not found")
+except AgentBerlinRateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except AgentBerlinError as e:
+    print(f"API error: {e.message}")
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

agentberlin-0.9.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+agentberlin/__init__.py,sha256=MMlz6BOMuAXTErssccHYbSP4AFAcA773hdcs-K83HxM,1327
+agentberlin/_http.py,sha256=_ZoYl5ro23Yub_5HTtS4qX-m0RlhFV2-mF2WLcTUgEA,5995
+agentberlin/client.py,sha256=MPy8MzI5yX7kru2_NI8LEXOOXzaLYZlAUuMmGEly9UE,2880
+agentberlin/config.py,sha256=qPGBExHv1sPY9o9CDrhnbHS9EDRPSn-_yg2zL2H6PNo,408
+agentberlin/exceptions.py,sha256=3YCqboljn9LSi0ueGDBR7h9lGKa0RbLD3LOmhqMZ5RU,2561
+agentberlin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentberlin/models/__init__.py,sha256=dumF4EML3WklZjpzYuqA35FeO97pntf8DZUPu6zNGuo,1100
+agentberlin/models/analytics.py,sha256=7Ot--db2VW5b0qnV04O_ZL5jIUlAnLIO_c0EjsePnXI,1849
+agentberlin/models/brand.py,sha256=UD9NdknaPt3vbFs9DhGzvsrw6WykMBJHKsBVllzAW9A,1131
+agentberlin/models/search.py,sha256=vZp-hR32CwDBagyngxw3N3-i7I4Ko-FrKDvxksEHHg8,2042
+agentberlin/models/serp.py,sha256=QyEdtVvzPpqjRtmxuX7sKtlcBnOhUQTsZPS3cwZuI0M,378
+agentberlin/resources/__init__.py,sha256=5_MjO0SyAxpR7QZkP9nYo5-m_ctsjwgAwxWDSYHyojo,349
+agentberlin/resources/analytics.py,sha256=iVcknPm6gZXt920xhlHy8Pk8T-WL-rYpung2qqrvEQs,1292
+agentberlin/resources/brand.py,sha256=tgV-YY2NS82-GRhBiwhgyvu5jgbMszZ1_wEVSXn5eOo,2752
+agentberlin/resources/keywords.py,sha256=cCluTqCplTom1YAqnZV8C5nJpiByQ1-SR-XtcoCV2sA,1548
+agentberlin/resources/pages.py,sha256=jeZu5JXr-rvGSepqoTsowkMQ1UFj5WBGPMckbPnIB0Q,3132
+agentberlin/resources/serp.py,sha256=MZdAIicsMewHVm3k5JkBBow6PipQrrTKjPi1P4sHz8o,1715
+agentberlin-0.9.0.dist-info/METADATA,sha256=7SebC4-n3E9Qe1WOQmpZa_IKJ4k7a3LQh2gQW97W9pE,4766
+agentberlin-0.9.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agentberlin-0.9.0.dist-info/licenses/LICENSE,sha256=BX6Yp57z81S2GsPrqvDKIucPL9jG5U3Jaqzn_dxO0wA,1069
+agentberlin-0.9.0.dist-info/RECORD,,

agentberlin-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentberlin-0.9.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Agent Berlin
+
+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.