knowledgesdk 0.2.0__tar.gz

knowledgesdk-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: Version bump type
+        required: true
+        default: patch
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/knowledgesdk
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Bump version
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          CURRENT=$(python -c "import re; print(re.search(r'version = \"(.+?)\"', open('pyproject.toml').read()).group(1))")
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+          case "${{ github.event.inputs.version_bump }}" in
+            major) MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 ;;
+            minor) MINOR=$((MINOR + 1)); PATCH=0 ;;
+            patch) PATCH=$((PATCH + 1)) ;;
+          esac
+          NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+          sed -i "s/version = \"${CURRENT}\"/version = \"${NEW_VERSION}\"/" pyproject.toml
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "chore: bump version to ${NEW_VERSION}"
+          git tag "v${NEW_VERSION}"
+          git push && git push --tags
+
+      - run: pip install build
+
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

knowledgesdk-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.env
+.DS_Store
+venv/
+.venv/

knowledgesdk-0.2.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: knowledgesdk
+Version: 0.2.0
+Summary: KnowledgeSDK Python SDK — Extract, classify and search web knowledge
+Project-URL: Homepage, https://knowledgesdk.com
+Project-URL: Repository, https://github.com/knowledgesdk/knowledgesdk-python
+Project-URL: Issues, https://github.com/knowledgesdk/knowledgesdk-python/issues
+Author: KnowledgeSDK
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KnowledgeSDK Python SDK
+
+Official Python client for the [KnowledgeSDK](https://knowledgesdk.com) API — extract, classify, scrape, screenshot, and search web knowledge programmatically.
+
+## Installation
+
+```bash
+pip install knowledgesdk
+```
+
+## Quick Start
+
+```python
+from knowledgesdk import KnowledgeSDK
+
+ks = KnowledgeSDK("sk_ks_your_key_here")
+```
+
+## Usage
+
+### Extract
+
+Run a full knowledge extraction on a website (synchronous):
+
+```python
+result = ks.extract.run("https://stripe.com")
+
+print(result.business.business_name)
+print(result.business.industry_sector)
+print(result.pages_scraped)
+
+for item in result.knowledge_items:
+    print(item.title, item.content)
+```
+
+Run an asynchronous extraction with a callback:
+
+```python
+job = ks.extract.run_async(
+    "https://stripe.com",
+    max_pages=20,
+    callback_url="https://myapp.com/webhook"
+)
+
+print(job.job_id)   # e.g. "job_abc123"
+print(job.status)   # e.g. "PENDING"
+```
+
+### Scrape
+
+Scrape a single web page and get its Markdown content:
+
+```python
+page = ks.scrape.run("https://docs.stripe.com/get-started")
+
+print(page.title)
+print(page.markdown)
+print(page.links)
+```
+
+### Classify
+
+Classify a business from its website:
+
+```python
+biz = ks.classify.run("https://stripe.com")
+
+print(biz.business_name)
+print(biz.business_type)
+print(biz.industry_sector)
+print(biz.target_audience)
+print(biz.confidence_score)
+```
+
+### Screenshot
+
+Capture a screenshot of a web page:
+
+```python
+shot = ks.screenshot.run("https://stripe.com")
+
+# shot.screenshot is a base64-encoded PNG string
+import base64
+image_bytes = base64.b64decode(shot.screenshot)
+with open("screenshot.png", "wb") as f:
+    f.write(image_bytes)
+```
+
+### Sitemap
+
+Fetch the sitemap for a website:
+
+```python
+site_map = ks.sitemap.run("https://stripe.com")
+
+print(site_map.count)
+for url in site_map.urls:
+    print(url)
+```
+
+### Search
+
+Search the extracted knowledge base:
+
+```python
+results = ks.search.run("pricing plans", limit=5)
+
+print(f"Found {results.total} results")
+for hit in results.hits:
+    print(hit.title, hit.score)
+    print(hit.content)
+```
+
+### Webhooks
+
+```python
+# Create a webhook
+wh = ks.webhooks.create(
+    url="https://myapp.com/hook",
+    events=["EXTRACTION_COMPLETED", "JOB_FAILED"],
+    display_name="My App Webhook"
+)
+print(wh.id)    # e.g. "weh_xxx"
+print(wh.token) # signing token
+
+# List all webhooks
+all_webhooks = ks.webhooks.list()
+for w in all_webhooks:
+    print(w.id, w.url, w.status)
+
+# Send a test event to a webhook
+ks.webhooks.test("weh_xxx")
+
+# Delete a webhook
+ks.webhooks.delete("weh_xxx")
+```
+
+### Jobs
+
+Retrieve a job by ID:
+
+```python
+job = ks.jobs.get("job_xxx")
+print(job.status)   # PENDING | RUNNING | COMPLETED | FAILED
+print(job.progress) # 0–100
+print(job.result)
+```
+
+Poll until a job completes (blocking):
+
+```python
+completed = ks.jobs.poll("job_xxx", interval_sec=5, timeout_sec=300)
+print(completed.result)
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `api_key` | required | API key starting with `sk_ks_` |
+| `base_url` | `https://api.knowledgesdk.com` | Override via `KNOWLEDGESDK_BASE_URL` env var |
+| `timeout` | `30000` | Request timeout in milliseconds |
+| `max_retries` | `5` | Max retries with exponential backoff |
+| `debug` | `False` | Enable request/response logging |
+
+### Environment Variables
+
+```bash
+export KNOWLEDGESDK_BASE_URL="https://api.knowledgesdk.com"
+```
+
+### Debug Mode
+
+```python
+ks = KnowledgeSDK("sk_ks_your_key", debug=True)
+
+# Or toggle at runtime
+ks.set_debug_mode(True)
+```
+
+### Custom Headers
+
+```python
+ks.set_header("X-Custom-Header", "value")
+ks.set_headers({"X-Header-A": "a", "X-Header-B": "b"})
+```
+
+## Error Handling
+
+```python
+from knowledgesdk import (
+    KnowledgeSDK,
+    AuthenticationError,
+    APIError,
+    RateLimitError,
+    NetworkError,
+    TimeoutError,
+)
+
+ks = KnowledgeSDK("sk_ks_your_key")
+
+try:
+    result = ks.extract.run("https://stripe.com")
+except AuthenticationError as e:
+    print(f"Auth error: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+except NetworkError as e:
+    print(f"Network error: {e.message}")
+except TimeoutError as e:
+    print(f"Request timed out: {e.message}")
+```
+
+## Type Reference
+
+All response objects are Pydantic models and are fully typed.
+
+| Type | Description |
+|---|---|
+| `ExtractResult` | Full extraction with business and knowledge items |
+| `BusinessClassification` | Business name, type, industry, audience, etc. |
+| `KnowledgeItem` | A single knowledge article extracted from a page |
+| `ScrapeResult` | Markdown content, title, description, links |
+| `ScreenshotResult` | Base64 PNG screenshot |
+| `SitemapResult` | List of URLs from the site's sitemap |
+| `SearchResult` | Search hits, total count, query |
+| `SearchHit` | Individual search result with score |
+| `AsyncJobRef` | Job ID and initial status for async operations |
+| `JobResult` | Full job status, progress, result, and error |
+| `WebhookFull` | Webhook ID, URL, events, status, token |
+
+## Requirements
+
+- Python >= 3.8
+- `requests >= 2.31.0`
+- `pydantic >= 2.0.0`
+
+## License
+
+MIT

knowledgesdk-0.2.0/README.md

@@ -0,0 +1,242 @@
+# KnowledgeSDK Python SDK
+
+Official Python client for the [KnowledgeSDK](https://knowledgesdk.com) API — extract, classify, scrape, screenshot, and search web knowledge programmatically.
+
+## Installation
+
+```bash
+pip install knowledgesdk
+```
+
+## Quick Start
+
+```python
+from knowledgesdk import KnowledgeSDK
+
+ks = KnowledgeSDK("sk_ks_your_key_here")
+```
+
+## Usage
+
+### Extract
+
+Run a full knowledge extraction on a website (synchronous):
+
+```python
+result = ks.extract.run("https://stripe.com")
+
+print(result.business.business_name)
+print(result.business.industry_sector)
+print(result.pages_scraped)
+
+for item in result.knowledge_items:
+    print(item.title, item.content)
+```
+
+Run an asynchronous extraction with a callback:
+
+```python
+job = ks.extract.run_async(
+    "https://stripe.com",
+    max_pages=20,
+    callback_url="https://myapp.com/webhook"
+)
+
+print(job.job_id)   # e.g. "job_abc123"
+print(job.status)   # e.g. "PENDING"
+```
+
+### Scrape
+
+Scrape a single web page and get its Markdown content:
+
+```python
+page = ks.scrape.run("https://docs.stripe.com/get-started")
+
+print(page.title)
+print(page.markdown)
+print(page.links)
+```
+
+### Classify
+
+Classify a business from its website:
+
+```python
+biz = ks.classify.run("https://stripe.com")
+
+print(biz.business_name)
+print(biz.business_type)
+print(biz.industry_sector)
+print(biz.target_audience)
+print(biz.confidence_score)
+```
+
+### Screenshot
+
+Capture a screenshot of a web page:
+
+```python
+shot = ks.screenshot.run("https://stripe.com")
+
+# shot.screenshot is a base64-encoded PNG string
+import base64
+image_bytes = base64.b64decode(shot.screenshot)
+with open("screenshot.png", "wb") as f:
+    f.write(image_bytes)
+```
+
+### Sitemap
+
+Fetch the sitemap for a website:
+
+```python
+site_map = ks.sitemap.run("https://stripe.com")
+
+print(site_map.count)
+for url in site_map.urls:
+    print(url)
+```
+
+### Search
+
+Search the extracted knowledge base:
+
+```python
+results = ks.search.run("pricing plans", limit=5)
+
+print(f"Found {results.total} results")
+for hit in results.hits:
+    print(hit.title, hit.score)
+    print(hit.content)
+```
+
+### Webhooks
+
+```python
+# Create a webhook
+wh = ks.webhooks.create(
+    url="https://myapp.com/hook",
+    events=["EXTRACTION_COMPLETED", "JOB_FAILED"],
+    display_name="My App Webhook"
+)
+print(wh.id)    # e.g. "weh_xxx"
+print(wh.token) # signing token
+
+# List all webhooks
+all_webhooks = ks.webhooks.list()
+for w in all_webhooks:
+    print(w.id, w.url, w.status)
+
+# Send a test event to a webhook
+ks.webhooks.test("weh_xxx")
+
+# Delete a webhook
+ks.webhooks.delete("weh_xxx")
+```
+
+### Jobs
+
+Retrieve a job by ID:
+
+```python
+job = ks.jobs.get("job_xxx")
+print(job.status)   # PENDING | RUNNING | COMPLETED | FAILED
+print(job.progress) # 0–100
+print(job.result)
+```
+
+Poll until a job completes (blocking):
+
+```python
+completed = ks.jobs.poll("job_xxx", interval_sec=5, timeout_sec=300)
+print(completed.result)
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `api_key` | required | API key starting with `sk_ks_` |
+| `base_url` | `https://api.knowledgesdk.com` | Override via `KNOWLEDGESDK_BASE_URL` env var |
+| `timeout` | `30000` | Request timeout in milliseconds |
+| `max_retries` | `5` | Max retries with exponential backoff |
+| `debug` | `False` | Enable request/response logging |
+
+### Environment Variables
+
+```bash
+export KNOWLEDGESDK_BASE_URL="https://api.knowledgesdk.com"
+```
+
+### Debug Mode
+
+```python
+ks = KnowledgeSDK("sk_ks_your_key", debug=True)
+
+# Or toggle at runtime
+ks.set_debug_mode(True)
+```
+
+### Custom Headers
+
+```python
+ks.set_header("X-Custom-Header", "value")
+ks.set_headers({"X-Header-A": "a", "X-Header-B": "b"})
+```
+
+## Error Handling
+
+```python
+from knowledgesdk import (
+    KnowledgeSDK,
+    AuthenticationError,
+    APIError,
+    RateLimitError,
+    NetworkError,
+    TimeoutError,
+)
+
+ks = KnowledgeSDK("sk_ks_your_key")
+
+try:
+    result = ks.extract.run("https://stripe.com")
+except AuthenticationError as e:
+    print(f"Auth error: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+except NetworkError as e:
+    print(f"Network error: {e.message}")
+except TimeoutError as e:
+    print(f"Request timed out: {e.message}")
+```
+
+## Type Reference
+
+All response objects are Pydantic models and are fully typed.
+
+| Type | Description |
+|---|---|
+| `ExtractResult` | Full extraction with business and knowledge items |
+| `BusinessClassification` | Business name, type, industry, audience, etc. |
+| `KnowledgeItem` | A single knowledge article extracted from a page |
+| `ScrapeResult` | Markdown content, title, description, links |
+| `ScreenshotResult` | Base64 PNG screenshot |
+| `SitemapResult` | List of URLs from the site's sitemap |
+| `SearchResult` | Search hits, total count, query |
+| `SearchHit` | Individual search result with score |
+| `AsyncJobRef` | Job ID and initial status for async operations |
+| `JobResult` | Full job status, progress, result, and error |
+| `WebhookFull` | Webhook ID, URL, events, status, token |
+
+## Requirements
+
+- Python >= 3.8
+- `requests >= 2.31.0`
+- `pydantic >= 2.0.0`
+
+## License
+
+MIT

knowledgesdk-0.2.0/knowledgesdk/__init__.py

@@ -0,0 +1,86 @@
+"""
+KnowledgeSDK Python SDK
+Official Python SDK for the KnowledgeSDK API
+"""
+
+from .client import KnowledgeSDK
+from .errors import (
+    KnowledgeSDKError,
+    APIError,
+    AuthenticationError,
+    NetworkError,
+    RateLimitError,
+    TimeoutError,
+)
+from .interfaces.types import (
+    # Client Options
+    KnowledgeSDKClientOptions,
+
+    # Extraction Types
+    KnowledgeItem,
+    BusinessClassification,
+    ExtractResult,
+
+    # Scrape Types
+    ScrapeResult,
+
+    # Screenshot Types
+    ScreenshotResult,
+
+    # Sitemap Types
+    SitemapResult,
+
+    # Search Types
+    SearchHit,
+    SearchResult,
+
+    # Job Types
+    AsyncJobRef,
+    JobResult,
+
+    # Webhook Types
+    WebhookFull,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main Client
+    "KnowledgeSDK",
+
+    # Errors
+    "KnowledgeSDKError",
+    "APIError",
+    "AuthenticationError",
+    "NetworkError",
+    "RateLimitError",
+    "TimeoutError",
+
+    # Client Options
+    "KnowledgeSDKClientOptions",
+
+    # Extraction Types
+    "KnowledgeItem",
+    "BusinessClassification",
+    "ExtractResult",
+
+    # Scrape Types
+    "ScrapeResult",
+
+    # Screenshot Types
+    "ScreenshotResult",
+
+    # Sitemap Types
+    "SitemapResult",
+
+    # Search Types
+    "SearchHit",
+    "SearchResult",
+
+    # Job Types
+    "AsyncJobRef",
+    "JobResult",
+
+    # Webhook Types
+    "WebhookFull",
+]

knowledgesdk-0.2.0/knowledgesdk/api/classify.py

@@ -0,0 +1,54 @@
+"""
+KnowledgeSDK Classify API
+"""
+
+from ..interfaces.types import BusinessClassification
+from ..utils.http_client import HttpClient
+
+
+class Classify:
+    """
+    Classify API resource
+
+    Classifies a business from its website URL.
+    """
+
+    def __init__(self, http_client: HttpClient):
+        self._http_client = http_client
+
+    def run(self, url: str) -> BusinessClassification:
+        """
+        Classify the business at the given URL.
+
+        Args:
+            url: The website URL to classify
+
+        Returns:
+            BusinessClassification with business name, type, industry, audience, etc.
+
+        Raises:
+            APIError: If the API returns an error response
+            NetworkError: If there's a network error
+            TimeoutError: If the request times out
+            AuthenticationError: If there's an authentication error
+        """
+        data = {"url": url}
+        response = self._http_client.request(
+            method="POST",
+            path="/classify",
+            data=data,
+        )
+
+        # Support both camelCase and snake_case response keys
+        return BusinessClassification(
+            business_name=response.get("businessName") or response.get("business_name"),
+            business_type=response.get("businessType") or response.get("business_type"),
+            industry_sector=response.get("industrySector") or response.get("industry_sector"),
+            target_audience=response.get("targetAudience") or response.get("target_audience"),
+            description=response.get("description"),
+            value_proposition=response.get("valueProposition") or response.get("value_proposition"),
+            pain_points=response.get("painPoints") or response.get("pain_points"),
+            unique_selling_points=response.get("uniqueSellingPoints") or response.get("unique_selling_points"),
+            key_insights=response.get("keyInsights") or response.get("key_insights"),
+            confidence_score=response.get("confidenceScore") or response.get("confidence_score"),
+        )