newco-sdk 0.1.1

NewCo Suite Python SDK — AuthPort + Clerk/Authentik/OIDC adapters + FastAPI dependencies

newco-sdk

Python SDK for the NewCo Suite. v0.1.0 ships the newco_sdk.auth surface only — AuthPort + Clerk / Authentik / OIDC adapter stubs + FastAPI Depends() helpers. Pydantic v2 models that mirror @newco-ai-platform/types/auth (TypeScript) field-for-field.

Agent, BaseTool, BaseLLMProvider re-exports are deferred to v0.2.0 (Phase 4 of the bootstrap plan) — NEURON vendors them directly in Phase 3, and the SDK extracts them once PRISM also needs them (lazy abstraction).

Why this exists

Every NewCo backend (PRISM, NEURON, VAULT, CATALYST, MERIDIAN, platform) needs to authenticate users without coupling to a specific identity provider. Business logic depends only on the AuthPort protocol; Clerk / Authentik / customer-OIDC slot in as adapters at runtime via the AUTH_PROVIDER env var.

This is the difference between a Clerk-locked app and one that ships sovereign deployments through Authentik on day one without touching application code.

Install

uv add newco-sdk             # via uv (recommended)
pip install newco-sdk        # via pip

Quick start (FastAPI)

from typing import Annotated
from fastapi import FastAPI, Depends
from newco_sdk.auth import User
from newco_sdk.auth.fastapi import get_current_user, require_permission

app = FastAPI()

@app.get("/me")
async def me(user: Annotated[User, Depends(get_current_user)]) -> dict:
    return {"id": str(user.id), "email": user.email}

@app.post("/workflows/{slug}/run")
async def run_workflow(
    slug: str,
    user: Annotated[User, Depends(require_permission("workflow:run"))],
) -> dict:
    return {"started_by": str(user.id), "workflow": slug}

Set AUTH_PROVIDER=clerk (or authentik, oidc) in the environment — no code change to swap providers.

What's in newco_sdk.auth

Symbol	Purpose
AuthPort	@runtime_checkable Protocol with verify, current_user, has_permission, list_orgs, sign_out. Business logic depends on this; never on a provider SDK directly.
User, Org, Role, Permission, Session, IdentityProvider	Pydantic v2 domain primitives. Field-for-field parity with @newco-ai-platform/types/auth. model_config = ConfigDict(extra="forbid") = the zod .strict() equivalent.
CURRENT_SCHEMA_VERSION	Constant = 1. Mirrors the TS export; must match across language boundaries.
get_auth_port()	Resolves the active adapter from AUTH_PROVIDER env var (defaults to clerk). Returns an AuthPort instance.
register_adapter(name, factory)	Register additional adapters (e.g. test fixtures, customer-specific OIDC variants).

What's deliberately NOT in v0.1.0

• Wired adapter implementations. ClerkAuthAdapter / AuthentikAuthAdapter / OIDCAuthAdapter are scaffolds — they satisfy the AuthPort protocol but every method raises NotImplementedError. Real wire-up to provider SDKs lands in a follow-up before NEURON Phase 3 needs to authenticate end-to-end.
• newco_sdk.agent / newco_sdk.tool / newco_sdk.llm. Deferred to v0.2.0 once PRISM also needs them — lazy abstraction.
• newco_sdk.hash_chain. Python implementation of the canonical-JSON + SHA-256 audit-chain spec from @newco-ai-platform/types/hash-chain. Will ship in v0.2.0 alongside Phase 2 step 10 (suite_contracts.md), with the cross-language conformance fixture 7909a7…fe36 as a binding test.

Schema version contract

Every cross-language envelope carries schema_version: int. The Python SDK exposes the same CURRENT_SCHEMA_VERSION = 1 constant. Consumers:

1. Match version → parse strictly. Pydantic models reject unknown keys (extra="forbid") and require schema_version to equal the literal value. A new field requires a schema_version bump in both TS and Python — out-of-sync bumps are caught by the parity tests.
2. Future version → log + drop. Consumer expecting v1 that receives v2 logs the rejection and drops the envelope. Never throws into the request pipeline.

Development

cd packages/sdk-py
uv sync                       # creates .venv, installs runtime + dev deps
uv run pytest                 # run tests
uv run mypy newco_sdk         # type-check
uv run ruff check             # lint
uv run ruff format            # auto-format

License

UNLICENSED — internal to NewCo Suite. Contact [e-mail] for licensing.