Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sidmanale643/northstar/llms.txt

Use this file to discover all available pages before exploring further.

The NorthStar Python SDK is published on PyPI as northstar-ai and supports Python 3.11 and later. The base package is intentionally lightweight — its only runtime dependencies are httpx, pydantic, python-dotenv, and requests. Heavier optional features such as LLM cost tracking and LLM-based eval graders are opt-in extras that pull in litellm only when you need it.

​
Requirements

  • Python >= 3.11
  • pip or uv (uv recommended for faster installs and lockfile management)

​
Installing the Package

uv add northstar-ai

​
Optional Extras

NorthStar ships two optional extras. Install whichever features your project requires by appending the extra name in brackets. 
uv add 'northstar-ai[pricing]'

uv add 'northstar-ai[evals]'
You can install both extras together: 
uv add 'northstar-ai[pricing,evals]'

​
What each extra provides

northstar-ai[pricing]

Pulls in litellm >= 1.50.0. Enables per-call token counting and USD cost calculation on every model_call span. Also required by northstar.llm.LLMService.

northstar-ai[evals]

Pulls in litellm >= 1.50.0. Enables LLM-judge graders in northstar.evals — including rubric_judge and faithfulness — that call a language model to score agent outputs.

​
Core Dependencies

These packages are installed automatically with the base northstar-ai package. You do not need to install them separately.
PackageVersionPurpose
httpx>= 0.27.0HTTP transport for the ingest worker with retry logic
pydantic>= 2.13.4Data models for Session, Run, Span, Event, and Score
python-dotenv>= 1.2.2Automatic .env file loading for credentials
requests>= 2.34.2HTTP client used by sync helper utilities

​
Environment Variables

NorthStar reads configuration from environment variables at init() time. Arguments passed directly to northstar.init() always take precedence over environment variables.
VariableDescription
NORTHSTAR_API_KEYRequired. Your project API key (starts with ns_).
NORTHSTAR_PROJECT_IDRequired. Your Supabase project reference string.
NORTHSTAR_ENABLEDtrue / false. Set to false to disable all SDK activity without removing instrumentation code. Default: true.
NORTHSTAR_DEBUGtrue / false. When enabled, the SDK prints [NorthStar] ... warnings to stderr for every flush and any errors. Default: false.
NORTHSTAR_PROJECTOptional label attached to every run’s metadata (e.g. "Support Agent").
NORTHSTAR_ENVIRONMENTOptional environment label attached to every run’s metadata (e.g. "production", "staging").
You can place NORTHSTAR_API_KEY and NORTHSTAR_PROJECT_ID in a .env file at your project root. NorthStar loads it automatically via python-dotenv — no extra setup required.

​
Local Development Setup

To contribute to NorthStar or run the test suite locally, clone the repository and install all development dependencies with uv: 
git clone <repo>
cd northstar
uv sync --group dev
The dev group installs pytest, pytest-asyncio, and respx (an HTTP mock library for testing httpx-based transports). Run the Python test suite with: 
uv run pytest -q tests
To run the Deno tests for the Supabase Edge Function: 
cd supabase/functions/ingest-traces && npx -y deno test --allow-env --allow-net index_test.ts

​
Verifying Your Installation

After installing, confirm the SDK initializes and can reach the ingest endpoint with this short snippet. If debug=True prints [NorthStar] sent N records after flush(), everything is wired up correctly. 
import northstar

northstar.init(
    api_key="ns_...",          # or rely on NORTHSTAR_API_KEY env var
    project_id="<project-ref>", # or rely on NORTHSTAR_PROJECT_ID env var
    debug=True,
)

@northstar.trace("smoke-test")
def hello() -> str:
    northstar.log_event("ping", {"status": "ok"})
    return "NorthStar is working"

print(hello())
northstar.flush(timeout=5)
If you see [NorthStar] disabled because NORTHSTAR_API_KEY and NORTHSTAR_PROJECT_ID are required in stderr, your credentials are not being read. Double-check that your environment variables are exported in the current shell session or present in your .env file.

Build docs developers (and LLMs) love

Get started for freeTalk to us