notpixel 0.1.0__tar.gz

notpixel-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.next/
+.turbo/
+out/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+.dev.vars
+.dev.vars.*
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+
+# TypeScript
+*.tsbuildinfo
+
+# Test coverage
+coverage/
+
+# Package manager locks (keep package-lock.json for now)
+yarn.lock
+pnpm-lock.yaml
+
+# Claude Code
+.claude/
+
+# Temporary files
+*.tmp
+*.temp
+
+# Generated tarballs
+*.tgz
+
+# Prisma
+server/prisma/migrations/.applied
+packages/landing/src/app/marketing/*
+packages/landing/src/app/marketing/
+!packages/landing/src/app/marketing/
+!packages/landing/src/app/marketing/assets.yaml
+
+.agent
+.agents
+.codex
+.vercel
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+build/

notpixel-0.1.0/LICENSE

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

notpixel-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: notpixel
+Version: 0.1.0
+Summary: NotPixel Python SDK — Privacy-first contextual ads for LLM applications (FastAPI, Django, LangChain, CrewAI)
+Project-URL: Homepage, https://notpixel.ai
+Project-URL: Documentation, https://docs.notpixel.ai/http-api
+Project-URL: Repository, https://github.com/Cocco-Enterprises/notpixel
+Author-email: NotPixel <dev@notpixel.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Contextual-ads,ads,ai,fastapi,langchain,llm,monetization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastembed<1,>=0.7.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# NotPixel Python SDK (`notpixel`)
+
+Official Python SDK for **NotPixel** — privacy-first contextual monetization for LLM applications, agents, and backends (**FastAPI, Django, Flask, LangChain, LlamaIndex, CrewAI**).
+
+## Installation
+
+```bash
+pip install notpixel
+```
+
+## Quick Start (Async — FastAPI / LangChain)
+
+```python
+from notpixel import AsyncAds
+
+# Privacy=True by default: generates 384-d embeddings locally (BAAI/bge-small-en-v1.5)
+# User prompts NEVER leave your server.
+ads = AsyncAds(publisher_id="pub_10565")
+
+# 1. Fetch a contextual ad + run your LLM in parallel (best-effort)
+result = await ads.respond(
+    input="How do I optimize PostgreSQL queries with indexes?",
+    llm=lambda: call_my_llm("How do I optimize PostgreSQL queries with indexes?"),
+)
+print(result.text)  # LLM response + sponsored ad block (if matched)
+
+# 2. Track events
+if result.ad:
+    await ads.impression(result.ad)
+    await ads.track_click(result.ad, metadata={"source": "fastapi_chat"})
+    await ads.track_conversion(
+        result.ad,
+        type="signup",
+        value_cents=2900,
+        external_id="order_12345",
+    )
+```
+
+## Synchronous Usage (Django WSGI / Scripts)
+
+```python
+from notpixel import Ads
+
+ads = Ads(publisher_id="pub_10565")
+ad = ads.get_ad(input="Best serverless Postgres database")
+if ad:
+    print(ad.text)
+    ads.track_click(ad)
+```
+
+## Privacy Modes
+
+- **`privacy=True` (Default)**: Generates `384`-dimensional embeddings locally using FastEmbed with the same quantized `Xenova/bge-small-en-v1.5` artifact as the TypeScript SDK, attention-mask **mean pooling** and L2 normalization. The built-in FastEmbed BGE entry uses CLS pooling and must not be substituted for this configuration. If local embedding fails, `get_ad()` emits `on_error` and returns `None` — **never** falling back to transmitting raw or sanitized text.
+- **`privacy=False`**: Sanitizes PII (emails, phone numbers), truncates to 256 characters, and sends `mode="standard"` to `https://api.notpixel.ai/api/v1/pick`.
+
+## Releases (maintainers)
+
+Python releases use their own version and tags (`python-v0.1.0`), independently of npm.
+Keep `pyproject.toml` and `src/notpixel/__init__.py` versions aligned.
+
+`.github/workflows/publish-python.yml` builds a wheel and source distribution, checks
+their metadata and contents, and installs the wheel with runtime dependencies to run
+the tests on Python 3.10–3.13. Tests use simulated transports and embeddings; they do
+not call production ad endpoints or download model weights.
+
+One-time setup: create the GitHub environment `pypi` and register a pending Trusted
+Publisher in [PyPI account publishing](https://pypi.org/manage/account/publishing/):
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `notpixel` |
+| GitHub owner | `Cocco-Enterprises` |
+| Repository | `notpixel` |
+| Workflow filename | `publish-python.yml` |
+| Environment | `pypi` |
+
+To release an already committed version:
+
+```bash
+git tag -a python-v0.1.0 -m "notpixel Python 0.1.0"
+git push origin python-v0.1.0
+```
+
+Only matching `python-v*` tags publish. Pull requests, pushes to `main`, and manual
+runs with `dry_run=true` build and test without uploading. Publishing uses PyPI
+Trusted Publishing (OIDC), with no permanent API token. After publication, confirm
+the version on PyPI and test `pip install notpixel==0.1.0` in a fresh environment.

notpixel-0.1.0/README.md

@@ -0,0 +1,87 @@
+# NotPixel Python SDK (`notpixel`)
+
+Official Python SDK for **NotPixel** — privacy-first contextual monetization for LLM applications, agents, and backends (**FastAPI, Django, Flask, LangChain, LlamaIndex, CrewAI**).
+
+## Installation
+
+```bash
+pip install notpixel
+```
+
+## Quick Start (Async — FastAPI / LangChain)
+
+```python
+from notpixel import AsyncAds
+
+# Privacy=True by default: generates 384-d embeddings locally (BAAI/bge-small-en-v1.5)
+# User prompts NEVER leave your server.
+ads = AsyncAds(publisher_id="pub_10565")
+
+# 1. Fetch a contextual ad + run your LLM in parallel (best-effort)
+result = await ads.respond(
+    input="How do I optimize PostgreSQL queries with indexes?",
+    llm=lambda: call_my_llm("How do I optimize PostgreSQL queries with indexes?"),
+)
+print(result.text)  # LLM response + sponsored ad block (if matched)
+
+# 2. Track events
+if result.ad:
+    await ads.impression(result.ad)
+    await ads.track_click(result.ad, metadata={"source": "fastapi_chat"})
+    await ads.track_conversion(
+        result.ad,
+        type="signup",
+        value_cents=2900,
+        external_id="order_12345",
+    )
+```
+
+## Synchronous Usage (Django WSGI / Scripts)
+
+```python
+from notpixel import Ads
+
+ads = Ads(publisher_id="pub_10565")
+ad = ads.get_ad(input="Best serverless Postgres database")
+if ad:
+    print(ad.text)
+    ads.track_click(ad)
+```
+
+## Privacy Modes
+
+- **`privacy=True` (Default)**: Generates `384`-dimensional embeddings locally using FastEmbed with the same quantized `Xenova/bge-small-en-v1.5` artifact as the TypeScript SDK, attention-mask **mean pooling** and L2 normalization. The built-in FastEmbed BGE entry uses CLS pooling and must not be substituted for this configuration. If local embedding fails, `get_ad()` emits `on_error` and returns `None` — **never** falling back to transmitting raw or sanitized text.
+- **`privacy=False`**: Sanitizes PII (emails, phone numbers), truncates to 256 characters, and sends `mode="standard"` to `https://api.notpixel.ai/api/v1/pick`.
+
+## Releases (maintainers)
+
+Python releases use their own version and tags (`python-v0.1.0`), independently of npm.
+Keep `pyproject.toml` and `src/notpixel/__init__.py` versions aligned.
+
+`.github/workflows/publish-python.yml` builds a wheel and source distribution, checks
+their metadata and contents, and installs the wheel with runtime dependencies to run
+the tests on Python 3.10–3.13. Tests use simulated transports and embeddings; they do
+not call production ad endpoints or download model weights.
+
+One-time setup: create the GitHub environment `pypi` and register a pending Trusted
+Publisher in [PyPI account publishing](https://pypi.org/manage/account/publishing/):
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `notpixel` |
+| GitHub owner | `Cocco-Enterprises` |
+| Repository | `notpixel` |
+| Workflow filename | `publish-python.yml` |
+| Environment | `pypi` |
+
+To release an already committed version:
+
+```bash
+git tag -a python-v0.1.0 -m "notpixel Python 0.1.0"
+git push origin python-v0.1.0
+```
+
+Only matching `python-v*` tags publish. Pull requests, pushes to `main`, and manual
+runs with `dry_run=true` build and test without uploading. Publishing uses PyPI
+Trusted Publishing (OIDC), with no permanent API token. After publication, confirm
+the version on PyPI and test `pip install notpixel==0.1.0` in a fresh environment.

notpixel-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "notpixel"
+version = "0.1.0"
+description = "NotPixel Python SDK — Privacy-first contextual ads for LLM applications (FastAPI, Django, LangChain, CrewAI)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+  { name = "NotPixel", email = "dev@notpixel.ai" }
+]
+keywords = ["llm", "ads", "monetization", "ai", "Contextual-ads", "fastapi", "langchain"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.25.0",
+  "fastembed>=0.7.0,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://notpixel.ai"
+Documentation = "https://docs.notpixel.ai/http-api"
+Repository = "https://github.com/Cocco-Enterprises/notpixel"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/notpixel"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/scripts", "/README.md", "/LICENSE", "/pyproject.toml"]
+core-metadata-version = "2.4"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

notpixel-0.1.0/scripts/check_distribution.py

@@ -0,0 +1,45 @@
+"""Check release archives before upload. Run with Python 3.11+ from any directory."""
+from __future__ import annotations
+
+import ast
+from email.parser import BytesParser
+import os
+from pathlib import Path
+import tarfile
+import tomllib
+import zipfile
+
+
+root = Path(__file__).resolve().parents[1]
+project = tomllib.loads((root / "pyproject.toml").read_text())["project"]
+version = project["version"]
+tree = ast.parse((root / "src/notpixel/__init__.py").read_text())
+code_version = next(ast.literal_eval(n.value) for n in tree.body
+                    if isinstance(n, ast.Assign)
+                    and any(isinstance(t, ast.Name) and t.id == "__version__" for t in n.targets))
+assert version == code_version, "Package and runtime versions differ"
+ref = os.environ.get("GITHUB_REF", "")
+if ref.startswith("refs/tags/python-v"):
+    assert ref.removeprefix("refs/tags/python-v") == version, "Tag must match package version"
+
+wheels = list((root / "dist").glob("*.whl"))
+sdists = list((root / "dist").glob("*.tar.gz"))
+assert len(wheels) == len(sdists) == 1, "Expected exactly one wheel and one sdist"
+with zipfile.ZipFile(wheels[0]) as wheel:
+    names = wheel.namelist()
+    assert "notpixel/py.typed" in names
+    assert "notpixel/client.py" in names and "notpixel/embedding.py" in names
+    assert all(n.startswith("notpixel/") or ".dist-info/" in n for n in names)
+    metadata = BytesParser().parsebytes(wheel.read(next(n for n in names if n.endswith("/METADATA"))))
+    assert metadata["Name"] == project["name"] and metadata["Version"] == version
+    assert metadata["Requires-Python"] == project["requires-python"]
+    assert metadata["License-Expression"] == "MIT"
+    assert any(n.endswith("/licenses/LICENSE") for n in names)
+    assert len(metadata.get_all("Requires-Dist", [])) >= len(project["dependencies"])
+with tarfile.open(sdists[0]) as sdist:
+    names = [m.name for m in sdist.getmembers() if m.isfile()]
+    assert all(n.startswith(f"notpixel-{version}/") for n in names)
+    assert any(n.endswith("/LICENSE") for n in names)
+    assert any(n.endswith("/src/notpixel/py.typed") for n in names)
+    assert not any("/.env" in n or "/__pycache__/" in n for n in names)
+print(f"Validated notpixel {version}: wheel, sdist, metadata, license, typing and release tag")

notpixel-0.1.0/src/notpixel/__init__.py

@@ -0,0 +1,71 @@
+from .cache import AdCache, generate_cache_key
+from .client import Ads, AsyncAds
+from .compose import compose_text, format_ad_block
+from .embedding import (
+    DEFAULT_MODEL,
+    LocalEmbeddingResult,
+    generate_local_embedding,
+    get_model_info,
+    is_model_loaded,
+    preload_embedding_model,
+    unload_model,
+)
+from .mock import MOCK_ADS
+from .sanitize import sanitize_and_truncate, sha256
+from .types import (
+    AD_EXPIRATION_MS,
+    Ad,
+    AdCTA,
+    AdEmptyEvent,
+    AdEmptyReason,
+    AdErrorEvent,
+    AdFetchedEvent,
+    AdsBatchResult,
+    AnalyticsHooks,
+    CacheConfig,
+    FeedbackResponse,
+    PrefetchResult,
+    PrivacyConfig,
+    RespondResult,
+    TrackClickResponse,
+    TrackConversionResponse,
+    is_ad_expired,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AD_EXPIRATION_MS",
+    "DEFAULT_MODEL",
+    "MOCK_ADS",
+    "Ad",
+    "AdCTA",
+    "AdCache",
+    "AdEmptyEvent",
+    "AdEmptyReason",
+    "AdErrorEvent",
+    "AdFetchedEvent",
+    "Ads",
+    "AdsBatchResult",
+    "AnalyticsHooks",
+    "AsyncAds",
+    "CacheConfig",
+    "FeedbackResponse",
+    "LocalEmbeddingResult",
+    "PrefetchResult",
+    "PrivacyConfig",
+    "RespondResult",
+    "TrackClickResponse",
+    "TrackConversionResponse",
+    "compose_text",
+    "format_ad_block",
+    "generate_cache_key",
+    "generate_local_embedding",
+    "get_model_info",
+    "is_ad_expired",
+    "is_model_loaded",
+    "preload_embedding_model",
+    "sanitize_and_truncate",
+    "sha256",
+    "unload_model",
+]

notpixel-0.1.0/src/notpixel/cache.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from .sanitize import sha256
+
+T = TypeVar("T")
+
+
+@dataclass
+class CacheEntry(Generic[T]):
+    value: T
+    expires_at: float
+
+
+class AdCache(Generic[T]):
+    def __init__(self, ttl_ms: int = 5 * 60 * 1000, max_size: int = 100) -> None:
+        self._cache: dict[str, CacheEntry[T]] = {}
+        self.ttl_ms = ttl_ms
+        self.max_size = max_size
+
+    def get(self, key: str) -> T | None:
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        if time.time() * 1000 > entry.expires_at:
+            self._cache.pop(key, None)
+            return None
+        return entry.value
+
+    def set(self, key: str, value: T) -> None:
+        if len(self._cache) >= self.max_size:
+            self.cleanup()
+        if len(self._cache) >= self.max_size and self._cache:
+            oldest_key = next(iter(self._cache))
+            self._cache.pop(oldest_key, None)
+        self._cache[key] = CacheEntry(
+            value=value,
+            expires_at=time.time() * 1000 + self.ttl_ms,
+        )
+
+    def delete(self, key: str) -> bool:
+        return self._cache.pop(key, None) is not None
+
+    def clear(self) -> None:
+        self._cache.clear()
+
+    def cleanup(self) -> int:
+        now = time.time() * 1000
+        expired = [k for k, v in self._cache.items() if now > v.expires_at]
+        for k in expired:
+            self._cache.pop(k, None)
+        return len(expired)
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "size": len(self._cache),
+            "maxSize": self.max_size,
+            "ttlMs": self.ttl_ms,
+        }
+
+
+def generate_cache_key(
+    publisher_id: str | None = None,
+    input_text: str | None = None,
+    mode: str | None = None,
+    embedding: list[float] | None = None,
+    context: dict[str, Any] | None = None,
+    request_id: str | None = None,
+) -> str:
+    embedding_key = (
+        sha256(",".join(f"{n:.6f}" for n in embedding))
+        if embedding
+        else ""
+    )
+    parts = [
+        publisher_id or "",
+        mode or "standard",
+        input_text or embedding_key or "",
+    ]
+    if context and len(context) > 0:
+        sorted_ctx = sorted(context.items(), key=lambda item: item[0])
+        parts.append(sha256(json.dumps(sorted_ctx, separators=(",", ":"))))
+    else:
+        parts.append("")
+    parts.append(sha256(request_id) if request_id else "")
+    # Fixed positions distinguish context, opportunity IDs and delimiters in input.
+    return json.dumps(parts, separators=(",", ":"))