Metadata-Version: 2.4
Name: newco-sdk
Version: 0.6.0
Summary: NewCo Suite Python SDK — AuthPort (auth) + MemoryPort (memory) + KnowledgePort (knowledge) + SemanticPort (semantic) + Clerk/Authentik/OIDC + HTTP adapters + FastAPI dependencies
Project-URL: Repository, https://github.com/newco-ai-platform/platform
Project-URL: Bug Tracker, https://github.com/newco-ai-platform/platform/issues
Author-email: Hardeep Arora <hardeeparora@gmail.com>
License: UNLICENSED
License-File: LICENSE
Keywords: auth,authentik,authport,clerk,fastapi,knowledge,knowledgeport,memory,memoryport,newco,oidc,ontology,rag,semantic,semanticport
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: clerk-backend-api<3.0,>=2.0
Requires-Dist: email-validator>=2.2.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.9.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

## Quick start (FastAPI)

```python
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

```bash
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 hardeeparora@gmail.com for licensing.
