Python SDK

Typed Python client built on httpx and Pydantic v2. Ships with py.typed for IDE autocomplete, automatic retries on 429, typed exceptions, and a default_feed option.

Installation

pip install postgrad

Quick Start

from postgrad import PostGrad

# default_feed="all" makes every search query fan out across all of
# your subscribed feeds. Alternatively pass a specific feed UUID, or
# omit default_feed to have PostGrad auto-select your most-populated feed.
client = PostGrad(api_key="pg_live_YOUR_API_KEY", default_feed="all")

# Search across all subscribed feeds and merge results by relevance.
# Each hit's metadata includes feed_id + feed_name.
results = client.search("pricing strategy")
for entry in results.data:
    print(f"{entry.title} (from {entry.feed_name}, {entry.confidence})")

# Override default_feed per-call when you want to scope to one feed.
results = client.search("pricing strategy", feed_id="b1a2c3d4-e5f6-7890-abcd-ef0123456789")

# List + get endpoints still require an explicit feed id.
entries = client.knowledge.list(
    feed_id="b1a2c3d4-e5f6-7890-abcd-ef0123456789",
    category="deal_evaluation",
    limit=10,
)

entry = client.knowledge.get(
    "entry-uuid-here",
    feed_id="b1a2c3d4-e5f6-7890-abcd-ef0123456789",
)
print(entry.data.content)

Client Options

client = PostGrad(
    api_key="pg_live_YOUR_API_KEY",
    base_url="https://postgrad.io",  # default
    timeout=30,  # request timeout in seconds (default: 30)
    # default_feed applies to every request unless overridden per-call.
    # Three accepted values:
    #   - "all" — fan out across every subscribed feed (search only)
    #   - a feed UUID — scope to that feed
    #   - None (omitted) — auto-select your most-populated feed (search only)
    default_feed="all",
)

Methods

`client.search(query, **kwargs)`

Search the knowledge base with natural language.

results = client.search(
    "AI agent architecture",
    categories=["ai_architecture", "tech_stack"],
    confidence_min=0.7,
    limit=20,
)

for entry in results.data:
    print(f"{entry.title} ({entry.confidence})")

`client.knowledge.list(**kwargs)`

List knowledge entries with optional filters.

entries = client.knowledge.list(
    category="sales_process",
    limit=25,
    offset=0,
)

`client.knowledge.get(id)`

Retrieve a single knowledge entry by ID.

entry = client.knowledge.get("550e8400-e29b-41d4-a716-446655440000")
print(entry.data.title)
print(entry.data.content)

`client.categories.list()`

List all available knowledge categories with entry counts.

categories = client.categories.list()
for cat in categories.data:
    print(f"{cat.name}: {cat.count} entries")

`client.usage.get()`

Check your current billing period usage.

usage = client.usage.get()
print(f"{usage.data.queries_used} / {usage.data.queries_limit} queries used")

Error Handling

The SDK raises typed exceptions for common failure scenarios.

from postgrad import PostGrad, PostGradError, RateLimitError, AuthError

client = PostGrad(api_key="pg_live_YOUR_API_KEY")

try:
    results = client.search("pricing")
except AuthError:
    print("Invalid or expired API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except PostGradError as e:
    print(f"API error: {e.message} ({e.status})")

Pydantic Models

All response objects are Pydantic models with full type information.

from postgrad.types import KnowledgeEntry, Category, UsageInfo

# KnowledgeEntry fields
entry: KnowledgeEntry
entry.id          # str (UUID)
entry.title       # str
entry.category    # str
entry.content     # str
entry.tags        # list[str]
entry.confidence  # float (0-1)
entry.reinforcement_count  # int
entry.created_at  # datetime
entry.updated_at  # datetime

# Category fields
cat: Category
cat.name   # str
cat.count  # int

# UsageInfo fields
usage: UsageInfo
usage.period_start      # datetime
usage.period_end        # datetime
usage.queries_used      # int
usage.queries_limit     # int
usage.queries_remaining # int
usage.tier              # str

Using the REST API Directly

If you prefer not to wait for the SDK, you can use requests or httpx directly:

import requests

API_KEY = "pg_live_YOUR_API_KEY"
BASE_URL = "https://postgrad.io/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    # "all" = fan out across every feed you're subscribed to.
    # Replace with a feed UUID to scope to one feed, or drop the header
    # entirely to let PostGrad auto-select.
    "X-PostGrad-Feed": "all",
}

# Search
response = requests.get(
    f"{BASE_URL}/knowledge/search",
    headers=headers,
    params={"q": "pricing strategy", "limit": 10},
)
data = response.json()

for entry in data["data"]:
    print(entry["title"])

Python SDK

On this page