wordlift-sdk 2.7.1__py3-none-any.whl

wordlift_sdk/graphql/client/client.py

@@ -0,0 +1,69 @@
+import os.path
+from typing import Any, Optional, Dict, List
+
+from gql import gql
+from graphql import parse, OperationDefinitionNode, FieldNode, DocumentNode
+
+from .gql_client_provider import GqlClientProvider
+
+
+class GraphQlQuery:
+    query: DocumentNode
+    fields: List[str]
+
+    def __init__(self, query: str):
+        self.query = gql(query)
+        self.fields = self.extract_field_names(query)
+
+    def get_query(self) -> DocumentNode:
+        return self.query
+
+    def get_fields(self) -> List[str]:
+        return self.fields
+
+    def extract_field_names(self, query_str):
+        parsed = parse(query_str)
+        for definition in parsed.definitions:
+            if isinstance(definition, OperationDefinitionNode):
+                for selection in definition.selection_set.selections:
+                    if selection.name.value == "entities":
+                        return [
+                            field.alias.value if field.alias else field.name.value
+                            for field in selection.selection_set.selections
+                            if isinstance(field, FieldNode)
+                        ]
+        return []
+
+
+file_contents = {}
+
+filenames = [
+    "entities_top_query.graphql",
+    "entities_url_id.graphql",
+    "entities_url_iri.graphql",
+]
+base_dir = os.path.dirname(os.path.abspath(__file__))
+
+for filename in filenames:
+    filepath = os.path.join(base_dir, "../data", filename)
+    with open(filepath, "r", encoding="utf-8") as f:
+        query = f.read()
+        file_contents[filename] = GraphQlQuery(query)
+
+
+class GraphQlClient:
+    _client_provider: GqlClientProvider
+
+    def __init__(self, client_provider: GqlClientProvider):
+        self._client_provider = client_provider
+
+    async def run(
+        self, graphql: str, variables: Optional[Dict[str, Any]] = None
+    ) -> list[dict[str, Any]]:
+        query = file_contents[graphql + ".graphql"]
+
+        # Asynchronous function to execute the query
+        async with self._client_provider.create() as session:
+            response = await session.execute(query.query, variable_values=variables)
+
+            return response["entities"]

wordlift_sdk/graphql/client/factory.py

@@ -0,0 +1,36 @@
+from gql import Client
+from gql.transport.aiohttp import AIOHTTPTransport
+
+from .client import GraphQlClient
+from .gql_client_provider import GqlClientProvider
+
+
+class GraphQlClientFactory:
+    _api_url: str
+    _key: str
+
+    def __init__(self, key: str, api_url: str = "https://api.wordlift.io/graphql"):
+        self._api_url = api_url
+        self._key = key
+
+    def create(self) -> GraphQlClient:
+        return GraphQlClient(self.create_provider())
+
+    def create_transport(self) -> AIOHTTPTransport:
+        # Select your transport with a defined url endpoint
+        return AIOHTTPTransport(
+            url=self._api_url,
+            ssl=True,
+            headers={"Authorization": f"Key {self._key}", "X-include-Private": "true"},
+        )
+
+    def create_gql_client(self) -> Client:
+        # Create a GraphQL client using the defined transport
+        return Client(
+            transport=self.create_transport(),
+            fetch_schema_from_transport=False,
+            execute_timeout=120,
+        )
+
+    def create_provider(self) -> GqlClientProvider:
+        return GqlClientProvider(key=self._key, api_url=self._api_url)

wordlift_sdk/graphql/client/gql_client_provider.py

@@ -0,0 +1,26 @@
+from gql import Client
+from gql.transport.aiohttp import AIOHTTPTransport
+
+
+class GqlClientProvider:
+    _api_url: str
+    _key: str
+
+    def __init__(self, key: str, api_url: str = "https://api.wordlift.io/graphql"):
+        self._api_url = api_url
+        self._key = key
+
+    def _create_transport(self) -> AIOHTTPTransport:
+        # Select your transport with a defined url endpoint
+        return AIOHTTPTransport(
+            url=self._api_url,
+            ssl=True,
+            headers={"Authorization": f"Key {self._key}", "X-include-Private": "true"},
+        )
+
+    def create(self) -> Client:
+        return Client(
+            transport=self._create_transport(),
+            fetch_schema_from_transport=False,
+            execute_timeout=120,
+        )

wordlift_sdk/graphql/data/entities_by_type.graphql

@@ -0,0 +1,9 @@
+query entities_by_type($types: [String]!) {
+    entities(
+        query: { typeConstraint: { in: $types } }
+    ) {
+        iri
+        keywords: string(name: "schema:keywords")
+        url: string(name: "schema:url")
+    }
+}

wordlift_sdk/graphql/data/entities_embedding_value.graphql

@@ -0,0 +1,15 @@
+query entities_embedding_value($url: String!) {
+    entities(
+        page: 0
+        rows: 1
+        query: {
+            urlConstraint: { in: [$url] }
+            embeddingValueConstraint: {
+                exists: { exists: true, excludeEmpty: false }
+            }
+        }
+    ) {
+        iri
+        embedding_value: string(name: "seovoc:embeddingValue")
+    }
+}

wordlift_sdk/graphql/data/entities_top_query.graphql

@@ -0,0 +1,20 @@
+query entities_top_query($urls: [String]!) {
+    entities(query: { urlConstraint: { in: $urls } }) {
+        iri
+        url: string(name: "schema:url")
+        name: string(name: "schema:name")
+        headline: string(name: "schema:headline")
+        title: string(name: "schema:title")
+        top_query: topN(
+            name: "seovoc:hasQuery"
+            sort: { field: "seovoc:impressions3Months", direction: DESC }
+            limit: 1
+        ) {
+            iri
+            name: string(name: "seovoc:name")
+            impressions: int(name: "seovoc:impressions3Months")
+            clicks: int(name: "seovoc:clicks3Months")
+            date_created: date(name: "seovoc:dateCreated")
+        }
+    }
+}

wordlift_sdk/graphql/data/entities_url_id.graphql

@@ -0,0 +1,6 @@
+query entities_url_id($urls: [String]!) {
+    entities(query: { urlConstraint: { in: $urls } } ) {
+        url: string(name:"schema:url")
+        id: iri
+    }
+}

wordlift_sdk/graphql/data/entities_url_iri.graphql

@@ -0,0 +1,7 @@
+query entities_url_id($urls: [String]!) {
+    entities(query: { urlConstraint: { in: $urls } } ) {
+        iri
+        url: string(name: "schema:url")
+        date_imported: dateTime(name: "seovoc:dateImported")
+    }
+}

wordlift_sdk/graphql/data/entities_url_iri_with_source_equal_to_web_page_import.graphql

@@ -0,0 +1,12 @@
+query entities_url_iri_with_source_equal_to_web_page_import($urls: [String]!) {
+    entities(
+        query: {
+            urlConstraint: { in: $urls }
+            typeConstraint: { in: [ "web-page-import" ] }
+        }
+    ) {
+        iri
+        url: string(name: "schema:url")
+        date_imported: dateTime(name: "seovoc:dateImported")
+    }
+}

wordlift_sdk/graphql/query.py

@@ -0,0 +1,20 @@
+from typing import Dict, Optional, Any
+from ..graphql.client import GraphQlClientFactory
+
+import pandas as pd
+
+
+async def query(key: str, query_string: str, root_element: str, columns: list[str],
+                variable_values: Optional[Dict[str, Any]] = None) -> pd.DataFrame:
+    from gql import gql
+
+    # Create a GraphQL client using the defined transport
+    client = GraphQlClientFactory(key=key).create_gql_client()
+
+    # Define the GraphQL query
+    gql_query = gql(query_string)
+
+    # Asynchronous function to execute the query
+    async with client as session:
+        response = await session.execute(gql_query, variable_values=variable_values)
+        return pd.DataFrame(response[root_element], columns=columns)

wordlift_sdk/graphql/utils/query/__init__.py

@@ -0,0 +1,4 @@
+from .entity_top_query import EntityTopQuery
+from .entity_with_top_query import entity_with_top_query_factory
+
+__all__ = ['EntityTopQuery', 'entity_with_top_query_factory']

wordlift_sdk/graphql/utils/query/entity_top_query.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+
+import pandas as pd
+
+
+@dataclass
+class EntityTopQuery:
+    iri: str
+    url: str
+    name: str
+    headline: str
+    title: str
+    top_query_iri: Optional[str] = field(default=None)
+    top_query_name: Optional[str] = field(default=None)
+    top_query_impressions: Optional[int] = field(default=None)
+    top_query_clicks: Optional[int] = field(default=None)
+    top_query_date_created: Optional[str] = field(default=None)
+
+    @staticmethod
+    def from_graphql_response(entity_data: dict) -> "EntityTopQuery":
+        # Initialize top_query fields with default values
+        top_query_iri = top_query_name = top_query_impressions = top_query_clicks = top_query_date_created = None
+
+        # Check if there are any top queries
+        if entity_data.get('top_query'):
+            top_query_data = entity_data['top_query'][0]
+            top_query_iri = top_query_data.get('iri')
+            top_query_name = top_query_data.get('name')
+            top_query_impressions = top_query_data.get('impressions')
+            top_query_clicks = top_query_data.get('clicks')
+            top_query_date_created = top_query_data.get('date_created')
+
+        # Create an Entity instance
+        return EntityTopQuery(
+            iri=entity_data['iri'],
+            url=entity_data['url'],
+            name=entity_data['name'],
+            headline=entity_data['headline'],
+            title=entity_data['title'],
+            top_query_iri=top_query_iri,
+            top_query_name=top_query_name,
+            top_query_impressions=top_query_impressions,
+            top_query_clicks=top_query_clicks,
+            top_query_date_created=top_query_date_created
+        )
+
+    def to_dataframe(self) -> pd.DataFrame:
+        entities_with_top_query_df = pd.DataFrame([asdict(self)])
+        entities_with_top_query_df['calc_name'] = entities_with_top_query_df[
+                                                      ['name', 'headline', 'title', 'url']].bfill(
+            axis=1).iloc[:, 0]
+        entities_with_top_query_df['top_query_date_created'] = pd.to_datetime(
+            entities_with_top_query_df['top_query_date_created'], errors='coerce')
+
+        return entities_with_top_query_df

wordlift_sdk/graphql/utils/query/entity_with_top_query.py

@@ -0,0 +1,52 @@
+from typing import Optional, Awaitable, Callable
+
+from tenacity import stop_after_attempt, retry, wait_fixed
+
+from .entity_top_query import EntityTopQuery
+from ...client import GraphQlClientFactory
+
+
+async def entity_with_top_query_factory(
+    key: str,
+) -> Callable[[str], Awaitable[Optional[EntityTopQuery]]]:
+    @retry(stop=stop_after_attempt(5), wait=wait_fixed(2))
+    async def entity_with_top_query(url: str) -> Optional[EntityTopQuery]:
+        from gql import gql
+
+        # Create a GraphQL client using the defined transport
+        client = GraphQlClientFactory(key=key).create_gql_client()
+
+        # Define the GraphQL query
+        gql_query = gql("""
+            query($url: String!) {
+              entities(query: { urlConstraint: { in: [$url] } }) {
+                iri
+                url: string(name: "schema:url")
+                name: string(name: "schema:name")
+                headline: string(name: "schema:headline")
+                title: string(name: "schema:title")
+                top_query: topN(
+                  name: "seovoc:hasQuery"
+                  sort: { field: "seovoc:impressions3Months", direction: DESC }
+                  limit: 1
+                ) {
+                  iri
+                  name: string(name: "seovoc:name")
+                  impressions: int(name: "seovoc:impressions3Months")
+                  clicks: int(name: "seovoc:clicks3Months")
+                  date_created: date(name: "seovoc:dateCreated")
+                }
+              }
+            }
+        """)
+
+        # Asynchronous function to execute the query
+        async with client as session:
+            response = await session.execute(gql_query, variable_values={"url": url})
+
+            if len(response["entities"]) == 0:
+                return None
+
+            return EntityTopQuery.from_graphql_response(response["entities"][0])
+
+    return entity_with_top_query

wordlift_sdk/id_generator/__init__.py

@@ -0,0 +1,3 @@
+from .id_generator import IdGenerator
+
+__all__ = ["IdGenerator"]

wordlift_sdk/id_generator/id_generator.py

@@ -0,0 +1,40 @@
+import re
+import unicodedata
+from urllib.parse import urljoin
+
+from wordlift_sdk.id_generator.id_generator_interface import IdGeneratorInterface
+from wordlift_client import AccountInfo
+
+
+class IdGenerator(IdGeneratorInterface):
+    account: AccountInfo
+
+    def __init__(self, account: AccountInfo):
+        self.account = account
+
+    def slugify(self, input_string: str) -> str:
+        if not isinstance(input_string, str):
+            return ''
+
+        # Insert dash between camelCase or PascalCase transitions: e.g. "ProfilePage" -> "Profile-Page"
+        input_string = re.sub(r'(?<=[a-z])(?=[A-Z])', '-', input_string)
+
+        # Normalize diacritics
+        slug = unicodedata.normalize('NFD', input_string)
+        slug = ''.join(c for c in slug if unicodedata.category(c) != 'Mn')
+
+        # Remove punctuation, convert to lowercase, format dashes
+        slug = re.sub(r'[^\w\s-]', '', slug)  # remove punctuation
+        slug = re.sub(r'\s+', '-', slug)  # replace spaces with dashes
+        slug = re.sub(r'-+', '-', slug)  # collapse multiple dashes
+        slug = slug.strip('-')  # trim leading/trailing dashes
+        slug = slug.lower()
+
+        return slug
+
+    def create(self, *args):
+        full_url = self.account.dataset_uri
+        for arg in args:
+            full_url = full_url.rstrip('/') + '/' + self.slugify(arg)
+
+        return full_url

wordlift_sdk/id_generator/id_generator_interface.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+
+class IdGeneratorInterface(ABC):
+
+    @abstractmethod
+    def create(self, *args):
+        pass

wordlift_sdk/internal_link/__init__.py

@@ -0,0 +1,3 @@
+from .utils import create_internal_link_handler
+
+__all__ = ['create_internal_link_handler']

wordlift_sdk/internal_link/utils.py

@@ -0,0 +1,231 @@
+import logging
+import re
+from typing import Callable, Awaitable
+from urllib.parse import quote
+
+import wordlift_client
+from pandas import Series
+from rdflib import Graph, URIRef, RDF, Literal, XSD
+from tenacity import retry, stop_after_attempt, wait_fixed
+from wordlift_client import InternalLinkRequest, InternalLink, InternalLinksApi, AnchorText, Item, \
+    VectorSearchQueryRequest, EntityPatchRequest, Configuration
+
+from wordlift_sdk import entity
+
+logger = logging.getLogger(__name__)
+
+
+async def create_internal_link_request_default_filter(row: Series, request: InternalLinkRequest) -> InternalLinkRequest:
+    return request
+
+
+@retry(
+    stop=stop_after_attempt(5),
+    wait=wait_fixed(2)
+)
+async def create_internal_link(
+        configuration: Configuration,
+        row: Series,
+        no_links: int = 10,
+        internal_link_request_filter: Callable[
+            [Series, InternalLinkRequest], Awaitable[
+                InternalLinkRequest]] = create_internal_link_request_default_filter
+) -> InternalLink | None:
+    import wordlift_client
+    entity_url = row['url']
+    entity_id = row['iri']
+
+    async with wordlift_client.ApiClient(configuration) as api_client:
+        api = InternalLinksApi(api_client)
+        request = await internal_link_request_filter(
+            row,
+            InternalLinkRequest(
+                anchor_text=AnchorText(
+                    enabled=True
+                ),
+                items=[
+                    Item(
+                        id=entity_id,
+                        query=VectorSearchQueryRequest(
+                            query_url=entity_url,
+                            similarity_top_k=no_links
+                        )
+                    )
+                ]
+            )
+        )
+
+        try:
+            results = await api.create_internal_link_suggestion(internal_link_request=request, _request_timeout=120)
+            return results[0]
+        except Exception as e:
+            logger.error("Error creating Internal Links: %s", e)
+            raise e
+
+
+class InternalLinkData:
+    source_id: str
+    source_patch_request: EntityPatchRequest
+    link_group_graph: Graph
+
+    def __init__(self, source_id: str, source_patch_request: EntityPatchRequest, link_group_graph: Graph):
+        self.source_id = source_id
+        self.source_patch_request = source_patch_request
+        self.link_group_graph = link_group_graph
+
+
+async def create_internal_link_data(internal_link: InternalLink, group_id: str) -> InternalLinkData:
+    """
+    Create an RDFlib Graph from an InternalLink object using the SEO vocabulary.
+
+    Args:
+        internal_link: InternalLink object from wordlift_client
+
+    Returns:
+        RDFlib Graph containing the mapped data
+        :param group_id:
+    """
+
+    # This is an example structure:
+    #
+    # InternalLink(
+    #     destinations=[
+    #         InternalLinkDestination(
+    #             name='SEO Strategies',
+    #             position=1,
+    #             url='https://wordlift.io/blog/en/advanced-seo-natural-language-processing/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='SERP Analysis',
+    #             position=2,
+    #             url='https://wordlift.io/blog/en/serp-analysis/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='Semantic Search',
+    #             position=3,
+    #             url='https://wordlift.io/blog/en/semantic-search/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='Text Summarize',
+    #             position=4,
+    #             url='https://wordlift.io/blog/en/text-summarization-in-seo/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='RankBrain In SEO',
+    #             position=5,
+    #             url='https://wordlift.io/blog/en/rankbrain-will-make-blog-worthless-unless/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='SEO and AI',
+    #             position=6,
+    #             url='https://wordlift.io/blog/en/how-expert-professional-seo-evolves-with-ai/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='Content Optimize',
+    #             position=7,
+    #             url='https://wordlift.io/blog/en/seo-content-optimization/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='Google Advances',
+    #             position=8,
+    #             url='https://wordlift.io/blog/en/advances-in-image-understanding/'
+    #         ),
+    #         InternalLinkDestination(
+    #             name='Knowledge Graphs',
+    #             position=9,
+    #             url='https://wordlift.io/blog/en/finding-entities-knowledge-graphs/'
+    #         )
+    #     ],
+    #     source=InternalLinkSource(
+    #         id='https://data.wordlift.io/wl1505904/title-tag-seo-using-deep-learning-and-tensorflow-3e9202b7c7a6fde83605021a5820ab04',
+    #         name=None,
+    #         url='https://wordlift.io/blog/en/title-tag-seo-using-ai/'
+    #     )
+    # )
+
+    # Validate group_id
+    if not group_id or not isinstance(group_id, str):
+        raise ValueError("group_id must be a non-empty string")
+
+    # Check for valid characters (alphanumeric, hyphen, underscore)
+    if not re.match(r'^[a-zA-Z0-9\-_]+$', group_id):
+        raise ValueError("group_id must contain only alphanumeric characters, hyphens, or underscores")
+
+    # URL encode the group_id for extra safety
+    safe_group_id = quote(group_id)
+
+    link_group_graph = Graph()
+    source_graph = Graph()
+
+    source_graph.bind("seovoc", "https://w3id.org/seovoc/")
+
+    # Define namespaces
+    link_group_graph.bind("seovoc", "https://w3id.org/seovoc/")
+    link_group_graph.bind("xsd", "http://www.w3.org/2001/XMLSchema#")
+
+    # Create source resource
+    source = internal_link.source
+    source_resource = URIRef(source.id)
+
+    # Create a default link group for the destinations
+    link_group_id = f"{source.id}/linkgroup_{safe_group_id}"
+    link_group = URIRef(link_group_id)
+
+    has_link_group = URIRef("https://w3id.org/seovoc/hasLinkGroup")
+    source_graph.add((source_resource, has_link_group, link_group))
+
+    link_group_graph.add((link_group, RDF.type, URIRef("https://w3id.org/seovoc/LinkGroup")))
+    link_group_graph.add((link_group, URIRef("https://w3id.org/seovoc/identifier"), Literal(group_id)))
+    link_group_graph.add((link_group, URIRef("https://w3id.org/seovoc/name"), Literal("Related Links")))
+    link_group_graph.add((link_group, URIRef("https://w3id.org/seovoc/isLinkGroupOf"), source_resource))
+
+    # Add destinations as links
+    for dest in internal_link.destinations:
+        # Create link resource
+        link_id = f"{link_group_id}/link_{dest.position}"
+        link_resource = URIRef(link_id)
+        link_group_graph.add((link_resource, RDF.type, URIRef("https://w3id.org/seovoc/Link")))
+
+        # Add link properties
+        link_group_graph.add(
+            (link_resource, URIRef("https://w3id.org/seovoc/position"), Literal(dest.position, datatype=XSD.integer)))
+        link_group_graph.add((link_resource, URIRef("https://w3id.org/seovoc/name"), Literal(dest.name)))
+        link_group_graph.add((link_resource, URIRef("https://w3id.org/seovoc/anchorText"), Literal(dest.name)))
+        link_group_graph.add((link_resource, URIRef("https://w3id.org/seovoc/anchorValue"), URIRef(dest.url)))
+        link_group_graph.add((link_resource, URIRef("https://w3id.org/seovoc/anchorResource"), URIRef(dest.id)))
+        link_group_graph.add((link_resource, URIRef("https://w3id.org/seovoc/isLinkOf"), link_group))
+        link_group_graph.add((link_group, URIRef("https://w3id.org/seovoc/hasLink"), link_resource))
+
+    source_patch_request = EntityPatchRequest(
+        op='add',
+        path='/' + str(has_link_group),
+        value=source_graph.serialize(format='json-ld', auto_compact=True)
+    )
+
+    return InternalLinkData(source.id, source_patch_request, link_group_graph)
+
+
+def create_internal_link_handler(
+        configuration: Configuration,
+        link_group_id: str,
+        no_links: int = 10,
+        internal_link_request_filter: Callable[
+            [Series, InternalLinkRequest], Awaitable[InternalLinkRequest]] = create_internal_link_request_default_filter
+) -> Callable[[Series], Awaitable[None]]:
+    async def handle(row: Series) -> None:
+        response = await create_internal_link(configuration, row, no_links, internal_link_request_filter)
+
+        if not response:
+            return
+
+        data = await create_internal_link_data(response, link_group_id)
+
+        await entity.patch(configuration, data.source_id, [data.source_patch_request])
+
+        async with wordlift_client.ApiClient(configuration) as api_client:
+            # Create an instance of the API class
+            api_instance = wordlift_client.EntitiesApi(api_client)
+            body = data.link_group_graph.serialize(format="turtle")
+            await api_instance.create_or_update_entities(body, _content_type="text/turtle")
+
+    return handle

wordlift_sdk/kg/__init__.py

@@ -0,0 +1,5 @@
+from .entity import Entity
+from .entity_store import EntityStore
+from .entity_store_factory import EntityStoreFactory
+
+__all__ = ["Entity", "EntityStore", "EntityStoreFactory"]

wordlift_sdk/kg/entity.py

@@ -0,0 +1,17 @@
+class Entity:
+    _props: dict[str, str]
+
+    def __init__(self, props: dict[str, str]):
+        self._props = props
+
+    @property
+    def iri(self) -> str:
+        return self._props['iri']
+
+    @property
+    def url(self) -> str:
+        return self._props['url']
+
+    @staticmethod
+    def from_dict(values: dict[str, str]):
+        return Entity(values)