matrixads 1.0.0__tar.gz

matrixads-1.0.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: matrixads
+Version: 1.0.0
+Summary: Python SDK for MatrixAds Conversational AI Monetization and Ad Network
+Author: MatrixAds Team
+Author-email: MatrixAds Team <sdk@matrixads.io>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Dynamic: author
+Dynamic: requires-python
+
+# matrixads
+
+> Python SDK for MatrixAds — Programmatic Conversational AI Ad Network & Monetization Engine.
+
+## Installation
+
+```bash
+pip install matrixads
+```
+
+With LangChain support:
+```bash
+pip install matrixads[langchain]
+```
+
+With CrewAI support:
+```bash
+pip install matrixads[crewai]
+```
+
+## Quick Start (Async)
+
+```python
+import asyncio
+from matrixads import MatrixAdsClient
+
+async def main():
+    client = MatrixAdsClient(publisher_key="mtx_pk_live_your_publisher_key")
+
+    response = await client.amatch_ad("I need cloud hosting for Next.js")
+
+    if response.match and response.ad:
+        print(f"Matched Headline: {response.ad.headline}")
+        print(f"CTA Link: {response.ad.cta_url}")
+
+        # Fire view impression beacon
+        await client.areport_impression(response.impression_token)
+
+asyncio.run(main())
+```
+
+## Quick Start (Sync)
+
+```python
+from matrixads import MatrixAdsClient
+
+client = MatrixAdsClient(publisher_key="mtx_pk_live_your_publisher_key")
+response = client.match_ad("Best B2B CRM software")
+
+if response.match and response.ad:
+    print(f"Sponsored: {response.ad.headline}")
+```
+
+## LangChain Integration
+
+```python
+from matrixads.langchain import MatrixAdsAdTool
+
+tool = MatrixAdsAdTool(publisher_key="mtx_pk_live_your_publisher_key")
+result = tool._run("I need a cloud hosting database solution")
+print(result)
+```
+
+## CrewAI Integration
+
+```python
+from crewai import Agent
+from matrixads.crewai import MatrixAdsCrewTool
+
+ad_tool = MatrixAdsCrewTool(publisher_key="mtx_pk_live_your_publisher_key")
+
+agent = Agent(
+    role="Tech Support Advisor",
+    goal="Answer software questions and include relevant sponsored solutions",
+    tools=[ad_tool]
+)
+```
+
+## License
+
+MIT © [MatrixAds](https://matrixads.io)

matrixads-1.0.0/README.md

@@ -0,0 +1,81 @@
+# matrixads
+
+> Python SDK for MatrixAds — Programmatic Conversational AI Ad Network & Monetization Engine.
+
+## Installation
+
+```bash
+pip install matrixads
+```
+
+With LangChain support:
+```bash
+pip install matrixads[langchain]
+```
+
+With CrewAI support:
+```bash
+pip install matrixads[crewai]
+```
+
+## Quick Start (Async)
+
+```python
+import asyncio
+from matrixads import MatrixAdsClient
+
+async def main():
+    client = MatrixAdsClient(publisher_key="mtx_pk_live_your_publisher_key")
+
+    response = await client.amatch_ad("I need cloud hosting for Next.js")
+
+    if response.match and response.ad:
+        print(f"Matched Headline: {response.ad.headline}")
+        print(f"CTA Link: {response.ad.cta_url}")
+
+        # Fire view impression beacon
+        await client.areport_impression(response.impression_token)
+
+asyncio.run(main())
+```
+
+## Quick Start (Sync)
+
+```python
+from matrixads import MatrixAdsClient
+
+client = MatrixAdsClient(publisher_key="mtx_pk_live_your_publisher_key")
+response = client.match_ad("Best B2B CRM software")
+
+if response.match and response.ad:
+    print(f"Sponsored: {response.ad.headline}")
+```
+
+## LangChain Integration
+
+```python
+from matrixads.langchain import MatrixAdsAdTool
+
+tool = MatrixAdsAdTool(publisher_key="mtx_pk_live_your_publisher_key")
+result = tool._run("I need a cloud hosting database solution")
+print(result)
+```
+
+## CrewAI Integration
+
+```python
+from crewai import Agent
+from matrixads.crewai import MatrixAdsCrewTool
+
+ad_tool = MatrixAdsCrewTool(publisher_key="mtx_pk_live_your_publisher_key")
+
+agent = Agent(
+    role="Tech Support Advisor",
+    goal="Answer software questions and include relevant sponsored solutions",
+    tools=[ad_tool]
+)
+```
+
+## License
+
+MIT © [MatrixAds](https://matrixads.io)

matrixads-1.0.0/matrixads/__init__.py

@@ -0,0 +1,23 @@
+from .client import (
+    MatrixAdsClient,
+    MatrixAdsAdResponse,
+    MatrixAdsAdPayload,
+    AdPromptClient,
+    AdPromptAdResponse,
+    AdPromptAdPayload,
+    SynapseClient,
+    SynapseAdResponse,
+    SynapseAdPayload,
+)
+
+__all__ = [
+    "MatrixAdsClient",
+    "MatrixAdsAdResponse",
+    "MatrixAdsAdPayload",
+    "AdPromptClient",
+    "AdPromptAdResponse",
+    "AdPromptAdPayload",
+    "SynapseClient",
+    "SynapseAdResponse",
+    "SynapseAdPayload",
+]

matrixads-1.0.0/matrixads/client.py

@@ -0,0 +1,126 @@
+from typing import Optional, Dict, Any
+import requests
+import httpx
+from pydantic import BaseModel
+
+class MatrixAdsAdPayload(BaseModel):
+    id: str
+    format: str = "CARD"
+    headline: str
+    body_text: str
+    cta_url: str
+    merchant: Optional[str] = None
+    disclosure_label: Optional[str] = None
+    clearing_price_usd: Optional[str] = None
+    match_score: Optional[float] = None
+    impression_token: Optional[str] = None
+
+AdPromptAdPayload = MatrixAdsAdPayload
+SynapseAdPayload = MatrixAdsAdPayload
+
+class MatrixAdsAdResponse(BaseModel):
+    match: bool
+    reason: Optional[str] = None
+    ad: Optional[MatrixAdsAdPayload] = None
+    impression_token: Optional[str] = None
+    latency_ms: Optional[float] = None
+
+AdPromptAdResponse = MatrixAdsAdResponse
+SynapseAdResponse = MatrixAdsAdResponse
+
+class MatrixAdsClient:
+    """
+    Python SDK Client for MatrixAds Conversational AI Ad Network.
+    Supports both synchronous and asynchronous ad matching and impression reporting.
+    """
+    def __init__(self, publisher_key: str, endpoint_url: str = "https://matrixads.io/api/v1/ads/match", timeout: float = 3.0):
+        self.publisher_key = publisher_key
+        self.endpoint_url = endpoint_url
+        self.timeout = timeout
+
+    def match_ad(self, prompt: str, session_id: Optional[str] = None) -> MatrixAdsAdResponse:
+        """
+        Synchronous ad match request.
+        """
+        payload = {
+            "prompt": prompt,
+            "publisher_key": self.publisher_key,
+        }
+        if session_id:
+            payload["session_id"] = session_id
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Publisher-Key": self.publisher_key,
+        }
+
+        try:
+            resp = requests.post(self.endpoint_url, json=payload, headers=headers, timeout=self.timeout)
+            if resp.status_code != 200:
+                return MatrixAdsAdResponse(
+                    match=False,
+                    reason=f"HTTP {resp.status_code}: {resp.text}"
+                )
+            data = resp.json()
+            return MatrixAdsAdResponse(**data)
+        except Exception as e:
+            return MatrixAdsAdResponse(match=False, reason=str(e))
+
+    async def amatch_ad(self, prompt: str, session_id: Optional[str] = None) -> MatrixAdsAdResponse:
+        """
+        Asynchronous ad match request for async frameworks (FastAPI, asyncio, LangChain).
+        """
+        payload = {
+            "prompt": prompt,
+            "publisher_key": self.publisher_key,
+        }
+        if session_id:
+            payload["session_id"] = session_id
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Publisher-Key": self.publisher_key,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(self.endpoint_url, json=payload, headers=headers)
+                if resp.status_code != 200:
+                    return MatrixAdsAdResponse(
+                        match=False,
+                        reason=f"HTTP {resp.status_code}: {resp.text}"
+                    )
+                data = resp.json()
+                return MatrixAdsAdResponse(**data)
+        except Exception as e:
+            return MatrixAdsAdResponse(match=False, reason=str(e))
+
+    def report_impression(self, impression_token: str) -> bool:
+        """
+        Report view impression beacon synchronously.
+        """
+        if not impression_token:
+            return False
+        try:
+            track_url = self.endpoint_url.replace("/ads/match", "/track/impression")
+            resp = requests.post(f"{track_url}?token={impression_token}", timeout=self.timeout)
+            return resp.status_code == 200
+        except Exception:
+            return False
+
+    async def areport_impression(self, impression_token: str) -> bool:
+        """
+        Report view impression beacon asynchronously.
+        """
+        if not impression_token:
+            return False
+        try:
+            track_url = self.endpoint_url.replace("/ads/match", "/track/impression")
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(f"{track_url}?token={impression_token}")
+                return resp.status_code == 200
+        except Exception:
+            return False
+
+AdPromptClient = MatrixAdsClient
+SynapseClient = MatrixAdsClient

matrixads-1.0.0/matrixads/crewai.py

@@ -0,0 +1,26 @@
+from typing import Optional
+from pydantic import BaseModel
+from .client import MatrixAdsClient
+
+class MatrixAdsCrewTool(BaseModel):
+    """
+    CrewAI Tool wrapper for MatrixAds contextual monetization.
+    Injects sponsored recommendation cards into autonomous CrewAI agent outputs.
+    """
+    name: str = "matrixads_ad_matcher"
+    description: str = "Retrieves contextual non-intrusive sponsored recommendation cards for user queries."
+    client: Optional[MatrixAdsClient] = None
+
+    def __init__(self, publisher_key: str, endpoint_url: str = "https://matrixads.io/api/v1/ads/match", **data):
+        super().__init__(**data)
+        self.client = MatrixAdsClient(publisher_key=publisher_key, endpoint_url=endpoint_url)
+
+    def run(self, query: str) -> str:
+        if not self.client:
+            return "MatrixAds client uninitialized."
+        res = self.client.match_ad(query)
+        if res.match and res.ad:
+            return f"[Sponsored Recommendation - {res.ad.disclosure_label or 'Ad'}]: {res.ad.headline} - {res.ad.body_text} ({res.ad.cta_url})"
+        return "No relevant sponsored ad matched."
+
+AdPromptCrewTool = MatrixAdsCrewTool

matrixads-1.0.0/matrixads/langchain.py

@@ -0,0 +1,26 @@
+from typing import Optional
+from pydantic import BaseModel
+from .client import MatrixAdsClient
+
+class MatrixAdsAdTool(BaseModel):
+    """
+    Tool wrapper for integrating MatrixAds with LangChain or CrewAI agents.
+    """
+    name: str = "matrixads_ad_matcher"
+    description: str = "Retrieves contextual non-intrusive sponsored recommendation cards for user queries."
+    client: Optional[MatrixAdsClient] = None
+
+    def __init__(self, publisher_key: str, endpoint_url: str = "https://matrixads.io/api/v1/ads/match", **data):
+        super().__init__(**data)
+        self.client = MatrixAdsClient(publisher_key=publisher_key, endpoint_url=endpoint_url)
+
+    def _run(self, query: str) -> str:
+        if not self.client:
+            return "MatrixAds client uninitialized."
+        res = self.client.match_ad(query)
+        if res.match and res.ad:
+            return f"[Sponsored by {res.ad.disclosure_label or 'Ad'}]: {res.ad.headline} - {res.ad.body_text} ({res.ad.cta_url})"
+        return "No relevant sponsored ad matched."
+
+AdPromptAdTool = MatrixAdsAdTool
+SynapseAdTool = MatrixAdsAdTool

matrixads-1.0.0/matrixads.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: matrixads
+Version: 1.0.0
+Summary: Python SDK for MatrixAds Conversational AI Monetization and Ad Network
+Author: MatrixAds Team
+Author-email: MatrixAds Team <sdk@matrixads.io>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Dynamic: author
+Dynamic: requires-python
+
+# matrixads
+
+> Python SDK for MatrixAds — Programmatic Conversational AI Ad Network & Monetization Engine.
+
+## Installation
+
+```bash
+pip install matrixads
+```
+
+With LangChain support:
+```bash
+pip install matrixads[langchain]
+```
+
+With CrewAI support:
+```bash
+pip install matrixads[crewai]
+```
+
+## Quick Start (Async)
+
+```python
+import asyncio
+from matrixads import MatrixAdsClient
+
+async def main():
+    client = MatrixAdsClient(publisher_key="mtx_pk_live_your_publisher_key")
+
+    response = await client.amatch_ad("I need cloud hosting for Next.js")
+
+    if response.match and response.ad:
+        print(f"Matched Headline: {response.ad.headline}")
+        print(f"CTA Link: {response.ad.cta_url}")
+
+        # Fire view impression beacon
+        await client.areport_impression(response.impression_token)
+
+asyncio.run(main())
+```
+
+## Quick Start (Sync)
+
+```python
+from matrixads import MatrixAdsClient
+
+client = MatrixAdsClient(publisher_key="mtx_pk_live_your_publisher_key")
+response = client.match_ad("Best B2B CRM software")
+
+if response.match and response.ad:
+    print(f"Sponsored: {response.ad.headline}")
+```
+
+## LangChain Integration
+
+```python
+from matrixads.langchain import MatrixAdsAdTool
+
+tool = MatrixAdsAdTool(publisher_key="mtx_pk_live_your_publisher_key")
+result = tool._run("I need a cloud hosting database solution")
+print(result)
+```
+
+## CrewAI Integration
+
+```python
+from crewai import Agent
+from matrixads.crewai import MatrixAdsCrewTool
+
+ad_tool = MatrixAdsCrewTool(publisher_key="mtx_pk_live_your_publisher_key")
+
+agent = Agent(
+    role="Tech Support Advisor",
+    goal="Answer software questions and include relevant sponsored solutions",
+    tools=[ad_tool]
+)
+```
+
+## License
+
+MIT © [MatrixAds](https://matrixads.io)

matrixads-1.0.0/matrixads.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+setup.py
+matrixads/__init__.py
+matrixads/client.py
+matrixads/crewai.py
+matrixads/langchain.py
+matrixads.egg-info/PKG-INFO
+matrixads.egg-info/SOURCES.txt
+matrixads.egg-info/dependency_links.txt
+matrixads.egg-info/requires.txt
+matrixads.egg-info/top_level.txt
+synapseads/__init__.py
+synapseads/client.py
+synapseads/langchain.py

matrixads-1.0.0/matrixads.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matrixads-1.0.0/matrixads.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.24.0
+pydantic>=2.0.0
+
+[crewai]
+crewai>=0.1.0
+
+[langchain]
+langchain-core>=0.1.0

matrixads-1.0.0/matrixads.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+matrixads
+synapseads

matrixads-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matrixads"
+version = "1.0.0"
+description = "Python SDK for MatrixAds Conversational AI Monetization and Ad Network"
+authors = [{ name = "MatrixAds Team", email = "sdk@matrixads.io" }]
+
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+crewai = ["crewai>=0.1.0"]

matrixads-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrixads-1.0.0/setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="matrixads",
+    version="1.0.0",
+    description="Python SDK for MatrixAds Conversational AI Monetization and Ad Network",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="MatrixAds Team",
+    author_email="sdk@matrixads.io",
+    packages=find_packages(),
+    install_requires=[
+        "httpx>=0.24.0",
+        "pydantic>=2.0.0",
+    ],
+    extras_require={
+        "langchain": ["langchain-core>=0.1.0"],
+        "crewai": ["crewai>=0.1.0"],
+    },
+    python_requires=">=3.9",
+)

matrixads-1.0.0/synapseads/__init__.py

@@ -0,0 +1,3 @@
+from .client import SynapseClient, SynapseAdResponse, SynapseAdPayload
+
+__all__ = ["SynapseClient", "SynapseAdResponse", "SynapseAdPayload"]

matrixads-1.0.0/synapseads/client.py

@@ -0,0 +1,74 @@
+import httpx
+from typing import Optional, Dict, Any
+from pydantic import BaseModel
+
+class SynapseAdPayload(BaseModel):
+    id: str
+    format: str
+    headline: str
+    body_text: str
+    cta_url: str
+    disclosure_label: str = "Sponsored"
+    clearing_price_usd: str
+    match_score: float
+
+class SynapseAdResponse(BaseModel):
+    match: bool
+    reason: Optional[str] = None
+    ad: Optional[SynapseAdPayload] = None
+    latency_ms: Optional[float] = None
+
+class SynapseClient:
+    """
+    Python SDK Client for AdPrompt Conversational Ad Network.
+    Supports both synchronous and asynchronous operations.
+    """
+    def __init__(
+        self,
+        publisher_key: str,
+        endpoint_url: str = "http://localhost:3000/api/v1/ads/match",
+        session_id: Optional[str] = None,
+        geo: Optional[str] = None,
+    ):
+        self.publisher_key = publisher_key
+        self.endpoint_url = endpoint_url
+        self.session_id = session_id
+        self.geo = geo
+
+    def match_ad(self, prompt: str) -> SynapseAdResponse:
+        """
+        Synchronous ad matching request for LLM pipelines and agent frameworks.
+        """
+        payload = {
+            "prompt": prompt,
+            "publisher_key": self.publisher_key,
+            "session_id": self.session_id,
+            "geo": self.geo,
+        }
+        with httpx.Client(timeout=3.0) as client:
+            resp = client.post(self.endpoint_url, json=payload)
+            if resp.status_code != 200:
+                return SynapseAdResponse(
+                    match=False,
+                    reason=f"HTTP {resp.status_code}: {resp.text}"
+                )
+            return SynapseAdResponse(**resp.json())
+
+    async def amatch_ad(self, prompt: str) -> SynapseAdResponse:
+        """
+        Asynchronous ad matching request.
+        """
+        payload = {
+            "prompt": prompt,
+            "publisher_key": self.publisher_key,
+            "session_id": self.session_id,
+            "geo": self.geo,
+        }
+        async with httpx.AsyncClient(timeout=3.0) as client:
+            resp = await client.post(self.endpoint_url, json=payload)
+            if resp.status_code != 200:
+                return SynapseAdResponse(
+                    match=False,
+                    reason=f"HTTP {resp.status_code}: {resp.text}"
+                )
+            return SynapseAdResponse(**resp.json())

matrixads-1.0.0/synapseads/langchain.py

@@ -0,0 +1,39 @@
+from typing import Optional, Type
+from pydantic import BaseModel, Field
+from .client import SynapseClient
+
+class AdMatchInput(BaseModel):
+    user_prompt: str = Field(description="The user's query or conversation prompt to evaluate for monetization ads.")
+
+class SynapseAdTool:
+    """
+    Tool wrapper for integrating AdPrompt with LangChain or CrewAI agents.
+    """
+    name: str = "synapse_ad_matcher"
+    description: str = "Monetize user queries by fetching relevant contextual sponsored cards or recommendations."
+    args_schema: Type[BaseModel] = AdMatchInput
+
+    def __init__(self, publisher_key: str, endpoint_url: str = "http://localhost:3000/api/v1/ads/match"):
+        self.client = SynapseClient(publisher_key=publisher_key, endpoint_url=endpoint_url)
+
+    def _run(self, user_prompt: str) -> str:
+        response = self.client.match_ad(user_prompt)
+        if not response.match or not response.ad:
+            return "No sponsored content matched for this query."
+        
+        ad = response.ad
+        return (
+            f"[{ad.disclosure_label}] {ad.headline}: {ad.body_text}\n"
+            f"Learn more: {ad.cta_url}"
+        )
+
+    async def _arun(self, user_prompt: str) -> str:
+        response = await self.client.amatch_ad(user_prompt)
+        if not response.match or not response.ad:
+            return "No sponsored content matched for this query."
+        
+        ad = response.ad
+        return (
+            f"[{ad.disclosure_label}] {ad.headline}: {ad.body_text}\n"
+            f"Learn more: {ad.cta_url}"
+        )