ntro 0.1.0__tar.gz

ntro-0.1.0/CLAUDE-ntro-python.md

@@ -0,0 +1,378 @@
+# ntro-python — Official Python SDK for the ntro platform
+
+## Project Overview
+
+This is the official Python SDK for the **ntro** platform. It provides the `ntro` package on PyPI.
+
+| Install | Import | What you get |
+|---------|--------|-------------|
+| `pip install ntro` | `from ntro.workspace import Client` | Workspace API client (control plane) |
+| (future) | `from ntro.workflow import workflow, activity` | Workflow framework (data plane) |
+
+**Today this repo contains `ntro.workspace` — the Python client for the Workspace API.** The workflow framework will be added later as `ntro.workflow` with optional dependency groups.
+
+The ntro platform automates fund administration (NAV calculation, document extraction, GL classification) for private markets firms. The Workspace API is the control plane backend (a separate TypeScript/NestJS service). This SDK is the Python interface to that API.
+
+**Naming convention:** follows the `{brand}-python` pattern used by Stripe (`stripe-python`), Auth0 (`auth0-python`), and Twilio (`twilio-python`). The repo is `ntro-python`, the PyPI package is `ntro`, the import is `from ntro import ...`.
+
+---
+
+## Architecture
+
+```
+┌─────────────┐  ┌─────────────┐
+│   ntro-cli  │  │  ntro-mcp   │   ← Separate repos, thin interface layers
+│   (Typer)   │  │  (future)   │
+└──────┬──────┘  └──────┬──────┘
+       │                │
+       ▼                ▼
+┌─────────────────────────────┐
+│     ntro (this package)     │   ← httpx + Pydantic, async-first
+│     ntro.workspace          │
+└──────────────┬──────────────┘
+               │ HTTP/REST
+               ▼
+┌─────────────────────────────┐
+│  Workspace API (TypeScript) │   ← Separate repo (NestJS)
+│  https://api.ntropii.com/v1│
+└─────────────────────────────┘
+```
+
+### Related repos
+
+| Repo | PyPI package | Binary | Purpose |
+|------|-------------|--------|---------|
+| **ntro-python** (this) | `ntro` | — | Python SDK |
+| ntro-cli | `ntro-cli` | `ntro` | CLI tool |
+| ntro-mcp | `ntro-mcp` | `ntro-mcp` | MCP server for Claude (future) |
+| ntro-workspace-api | — | — | TypeScript/NestJS backend |
+
+---
+
+## Repository Structure
+
+```
+ntro-python/
+├── CLAUDE.md                        # ← This file
+├── pyproject.toml                   # Package metadata, dependencies, build config
+├── README.md
+│
+├── src/
+│   └── ntro/
+│       ├── __init__.py              # Top-level exports
+│       │
+│       └── workspace/               # Workspace API client (control plane)
+│           ├── __init__.py          # Exports Client
+│           ├── client.py            # Main client class, resource mounting
+│           ├── config.py            # TOML config loading (~/.ntro/config.toml, env vars)
+│           ├── auth.py              # Auth handling (API key for PoC, OAuth future)
+│           ├── exceptions.py        # Typed exceptions (NtroAPIError, NotFoundError, etc.)
+│           ├── http.py              # httpx wrapper, retry logic, error mapping
+│           │
+│           ├── models/              # Pydantic v2 models (request/response DTOs)
+│           │   ├── __init__.py
+│           │   ├── common.py        # Pagination, enums (Provider, Status, etc.)
+│           │   ├── identity.py      # UserProfile
+│           │   ├── integration.py   # DataPlatformConfig, EmailIntegration, SchemaInfo
+│           │   ├── tenant.py        # Tenant, CreateTenantRequest
+│           │   ├── entity.py        # Entity, CreateEntityRequest
+│           │   ├── workflow.py      # Workflow, WorkflowVersion, Capability
+│           │   ├── deployment.py    # Deployment, DeploymentStatus
+│           │   └── task.py          # Task, TaskStep, TaskStatus
+│           │
+│           └── resources/           # API resource classes (one per domain)
+│               ├── __init__.py
+│               ├── identity.py      # IdentityResource — GET /me
+│               ├── integrations.py  # IntegrationsResource — /workspace/data/*, /workspace/integrations/*
+│               ├── tenants.py       # TenantsResource — /workspace/tenants/*
+│               ├── entities.py      # EntitiesResource — /workspace/entities, /workspace/tenants/{id}/entities
+│               ├── workflows.py     # WorkflowsResource — /workspace/registry/workflows/*
+│               ├── deployments.py   # DeploymentsResource — /workspace/registry/deployments/*
+│               └── tasks.py         # TasksResource — /workspace/tasks/*, /workspace/schedule, etc.
+│
+├── tests/
+│   ├── unit/                        # Mocked HTTP via respx
+│   └── integration/                 # Against running API
+│
+└── docs/
+```
+
+---
+
+## Package Configuration
+
+```toml
+# pyproject.toml
+[project]
+name = "ntro"
+version = "0.1.0"
+description = "Official Python SDK for the ntro platform"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "tomli-w>=1.0",
+]
+
+[project.optional-dependencies]
+# Future: workflow framework deps
+# workflow = ["temporalio>=1.7", "pdfplumber>=0.11"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ntro"]
+```
+
+---
+
+## SDK Design
+
+### Client
+
+```python
+from ntro.workspace import Client
+
+# From config file (reads ~/.ntro/config.toml)
+client = Client.from_config()                         # uses default connection
+client = Client.from_config(connection="staging")      # specific connection
+
+# Explicit (for scripting / testing)
+client = Client(
+    host="http://localhost:3000/v1",
+    api_key="ntro_test_key",
+)
+
+# Async (MCP server, notebooks)
+tenant = await client.tenants.create(name="Acme", slug="acme", data_platform_config_id="dpc_123")
+
+# Sync (CLI, simple scripts)
+tenant = client.tenants.create_sync(name="Acme", slug="acme", data_platform_config_id="dpc_123")
+```
+
+### Resource Pattern
+
+```python
+# src/ntro/workspace/resources/tenants.py
+from ntro.workspace.http import HttpClient
+from ntro.workspace.models.tenant import Tenant, CreateTenantRequest
+
+class TenantsResource:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    async def create(self, *, name: str, slug: str, data_platform_config_id: str) -> Tenant:
+        dto = CreateTenantRequest(name=name, slug=slug, data_platform_config_id=data_platform_config_id)
+        response = await self._http.post("/workspace/tenants", json=dto.model_dump())
+        return Tenant.model_validate(response)
+
+    def create_sync(self, **kwargs) -> Tenant:
+        return asyncio.run(self.create(**kwargs))
+
+    async def list(self) -> list[Tenant]:
+        response = await self._http.get("/workspace/tenants")
+        return [Tenant.model_validate(t) for t in response]
+
+    def list_sync(self) -> list[Tenant]:
+        return asyncio.run(self.list())
+
+    async def get(self, id: str) -> Tenant:
+        response = await self._http.get(f"/workspace/tenants/{id}")
+        return Tenant.model_validate(response)
+
+    def get_sync(self, id: str) -> Tenant:
+        return asyncio.run(self.get(id))
+```
+
+### HTTP Client
+
+Use **httpx** with:
+- Async by default (`httpx.AsyncClient`)
+- Sync wrappers using `asyncio.run()` for CLI consumers
+- Base URL injection from config
+- Auth header injection (`Authorization: Bearer <api_key>`)
+- Automatic retry with exponential backoff for 5xx errors
+- Error mapping: 404 → `NotFoundError`, 422 → `ValidationError`, 401 → `AuthenticationError`
+- Request/response logging at DEBUG level
+
+### Pydantic Models
+
+All request and response bodies are Pydantic v2 models:
+
+```python
+# src/ntro/workspace/models/common.py
+from enum import Enum
+
+class Provider(str, Enum):
+    DATABRICKS = "DATABRICKS"
+    SNOWFLAKE = "SNOWFLAKE"
+    MICROSOFT_FABRIC = "MICROSOFT_FABRIC"
+    GCP_BIGQUERY = "GCP_BIGQUERY"
+
+class TaskStatus(str, Enum):
+    PENDING = "PENDING"
+    IN_PROGRESS = "IN_PROGRESS"
+    BLOCKED = "BLOCKED"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+
+class TenantStatus(str, Enum):
+    PROVISIONING = "PROVISIONING"
+    ACTIVE = "ACTIVE"
+    SUSPENDED = "SUSPENDED"
+```
+
+### Configuration (TOML, Snowflake CLI-style connections)
+
+Config follows the Snowflake CLI convention (`config.toml` with `[connections.<n>]` sections).
+
+**Config file:** `~/.ntro/config.toml`
+
+```toml
+# ~/.ntro/config.toml
+
+default_connection_name = "local"
+
+[connections.local]
+host = "http://localhost:3000/v1"
+api_key = "ntro_dev_key"
+default_tenant = "acme-fund-admin"
+
+[connections.staging]
+host = "https://staging.api.ntropii.com/v1"
+api_key = "ntro_staging_key"
+default_tenant = "test-fund-admin"
+
+[connections.production]
+host = "https://api.ntropii.com/v1"
+api_key = "ntro_prod_key"
+default_tenant = "acme-fund-admin"
+
+[cli]
+output_format = "table"
+
+[cli.logs]
+save_logs = true
+level = "info"
+path = "~/.ntro/logs"
+```
+
+**Resolution priority:**
+1. Explicit constructor args
+2. Environment variables: `NTRO_HOST`, `NTRO_API_KEY`
+3. Per-connection env var overrides: `NTRO_CONNECTIONS_<n>_API_KEY`
+4. Named connection in config.toml
+5. `default_connection_name` in config.toml
+
+**Config file location:**
+1. `NTRO_HOME` env var → `$NTRO_HOME/config.toml`
+2. `~/.ntro/config.toml`
+
+Parsed with Python 3.11+ built-in `tomllib` (read) and `tomli_w` (write).
+
+---
+
+## Endpoint → SDK Method Mapping
+
+### Phase 0 — Bootstrap
+| API Endpoint | SDK Method |
+|---|---|
+| `GET /me` | `client.identity.whoami()` |
+
+### Phase 1 — Data Platform & Integrations
+| API Endpoint | SDK Method |
+|---|---|
+| `POST /workspace/data` | `client.integrations.create_data_platform()` |
+| `GET /workspace/data` | `client.integrations.list_data_platforms()` |
+| `GET /workspace/data/{id}` | `client.integrations.get_data_platform(id)` |
+| `POST /workspace/data/{id}/test` | `client.integrations.test_connection(id)` |
+| `GET /workspace/data/{id}/schemas` | `client.integrations.discover_schemas(id)` |
+| `GET /workspace/data/{id}/tenants` | `client.integrations.list_platform_tenants(id)` |
+| `POST /workspace/integrations/email` | `client.integrations.create_email(...)` |
+| `GET /workspace/integrations` | `client.integrations.list_all()` |
+
+### Phase 2 — Tenant & Entity
+| API Endpoint | SDK Method |
+|---|---|
+| `POST /workspace/tenants` | `client.tenants.create()` |
+| `GET /workspace/tenants` | `client.tenants.list()` |
+| `GET /workspace/tenants/{id}` | `client.tenants.get(id)` |
+| `POST /workspace/tenants/{id}/entities` | `client.entities.create(tenant_id, ...)` |
+| `GET /workspace/entities` | `client.entities.list()` |
+
+### Phase 3 — Workflow Registry
+| API Endpoint | SDK Method |
+|---|---|
+| `POST /workspace/registry/workflows` | `client.workflows.create()` |
+| `GET /workspace/registry/workflows` | `client.workflows.list()` |
+| `GET /workspace/registry/workflows/{id}` | `client.workflows.get(id)` |
+| `POST /workspace/registry/workflows/{id}/versions` | `client.workflows.push(id, artifact)` |
+| `POST /workspace/registry/capabilities` | `client.workflows.create_capability()` |
+
+### Phase 4 — Deployment
+| API Endpoint | SDK Method |
+|---|---|
+| `POST /workspace/registry/deployments` | `client.deployments.create()` |
+| `GET /workspace/registry/deployments/{id}` | `client.deployments.get(id)` |
+
+### Phase 5 — Execution
+| API Endpoint | SDK Method |
+|---|---|
+| `POST /workspace/tasks` | `client.tasks.create()` |
+| `GET /workspace/tasks/{id}` | `client.tasks.get(id)` |
+| `GET /workspace/schedule` | `client.tasks.list_schedule()` |
+| `GET /workspace/tenants/{tid}/entities/{eid}/tasks` | `client.tasks.history(tenant_id, entity_id)` |
+| `GET /workspace/incoming` | `client.tasks.list_incoming()` |
+| `GET /workspace/pending` | `client.tasks.list_pending()` |
+
+---
+
+## Build Order
+
+1. **Scaffold** — pyproject.toml, directory structure, dev tooling
+2. **Core** — `http.py` (httpx wrapper), `config.py` (TOML loading), `auth.py`, `exceptions.py`
+3. **Phase 0** — `resources/identity.py` + `models/identity.py` → `client.identity.whoami()`
+4. **Phase 1** — `resources/integrations.py` + `models/integration.py`
+5. **Phase 2** — `resources/tenants.py` + `resources/entities.py` + models
+6. **Phase 3** — `resources/workflows.py` + models
+7. **Phase 4** — `resources/deployments.py` + models
+8. **Phase 5** — `resources/tasks.py` + models
+
+Each phase: resource + models → unit tests (mocked HTTP via respx).
+
+---
+
+## PoC Scope
+
+### In scope
+- All P0 SDK methods (18 endpoints)
+- TOML config file support
+- Async + sync wrappers
+- Pydantic v2 models (hand-written)
+- Unit tests with respx
+
+### Excluded
+- `ntro.workflow` module (workflow framework — future)
+- OAuth / OIDC auth (PoC uses API key)
+- Auto-generated models from OpenAPI spec
+- PyPI publishing
+
+---
+
+## Domain Context
+
+- **Tenant** = client organisation (fund admin or asset manager). Contains entities.
+- **Entity** = SPV or fund within a tenant. Own schema in customer's Databricks.
+- **Workflow** = repeatable process (NAV calc, doc ingestion, period close). Registered, deployed, triggered.
+- **Task** = running instance of a workflow, scoped to an entity.
+- **Data Platform** = customer's Databricks/Snowflake/Fabric where financial data lives.
+- **Built-in workflows** = `coa-import`, `document-ingest`, `nav-monthly`, `period-close`.

ntro-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: ntro
+Version: 0.1.0
+Summary: Official Python SDK for the ntro platform
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'

ntro-0.1.0/README.md

@@ -0,0 +1,2 @@
+# ntro-python
+Python library for ntropii framework

ntro-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "ntro"
+version = "0.1.0"
+description = "Official Python SDK for the ntro platform"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "tomli-w>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ntro"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

ntro-0.1.0/src/ntro/__init__.py

@@ -0,0 +1,5 @@
+"""ntro — Official Python SDK for the ntro platform."""
+
+from ntro.workspace import Client
+
+__all__ = ["Client"]

ntro-0.1.0/src/ntro/workspace/__init__.py

@@ -0,0 +1,5 @@
+"""ntro.workspace — Workspace API client (control plane)."""
+
+from ntro.workspace.client import Client
+
+__all__ = ["Client"]

ntro-0.1.0/src/ntro/workspace/client.py

@@ -0,0 +1,68 @@
+"""Main Client class for the ntro Workspace API."""
+
+from __future__ import annotations
+
+import os
+
+from ntro.workspace.config import ConnectionConfig, load_config
+from ntro.workspace.http import HttpClient
+from ntro.workspace.resources.deployments import DeploymentsResource
+from ntro.workspace.resources.entities import EntitiesResource
+from ntro.workspace.resources.identity import IdentityResource
+from ntro.workspace.resources.integrations import IntegrationsResource
+from ntro.workspace.resources.tasks import TasksResource
+from ntro.workspace.resources.tenants import TenantsResource
+from ntro.workspace.resources.workflows import WorkflowsResource
+
+
+class Client:
+    """Workspace API client.
+
+    Usage:
+        # From config file (reads ~/.ntro/config.toml)
+        client = Client.from_config()
+        client = Client.from_config(connection="staging")
+
+        # Explicit (for scripting / testing)
+        client = Client(host="http://localhost:3000/v1", api_key="ntro_dev_key")
+    """
+
+    def __init__(
+        self,
+        host: str = "https://api.ntropii.com/v1",
+        api_key: str = "",
+        debug: bool = False,
+    ) -> None:
+        self._http = HttpClient(base_url=host, api_key=api_key, debug=debug)
+        self.identity = IdentityResource(self._http)
+        self.integrations = IntegrationsResource(self._http)
+        self.tenants = TenantsResource(self._http)
+        self.entities = EntitiesResource(self._http)
+        self.workflows = WorkflowsResource(self._http)
+        self.deployments = DeploymentsResource(self._http)
+        self.tasks = TasksResource(self._http)
+
+    @classmethod
+    def from_config(
+        cls,
+        connection: str | None = None,
+        debug: bool = False,
+    ) -> "Client":
+        """Create a Client from ~/.ntro/config.toml.
+
+        Resolution priority:
+        1. NTRO_HOST / NTRO_API_KEY env vars (override config)
+        2. Named connection (--connection flag or NTRO_DEFAULT_CONNECTION_NAME env var)
+        3. default_connection_name in config.toml
+        """
+        conn_name = connection or os.environ.get("NTRO_DEFAULT_CONNECTION_NAME")
+        config = load_config()
+        conn: ConnectionConfig = config.get_connection(conn_name)
+
+        host = os.environ.get("NTRO_HOST") or conn.host
+        api_key = os.environ.get("NTRO_API_KEY") or conn.api_key
+
+        return cls(host=host, api_key=api_key, debug=debug)
+
+    async def close(self) -> None:
+        await self._http.close()

ntro-0.1.0/src/ntro/workspace/config.py

@@ -0,0 +1,145 @@
+"""TOML-based config loading for ntro SDK.
+
+Config file: ~/.ntro/config.toml  (or $NTRO_HOME/config.toml)
+
+Example:
+    default_connection_name = "local"
+
+    [connections.local]
+    host = "http://localhost:3000/v1"
+    api_key = "ntro_dev_key"
+    default_tenant = "acme-fund-admin"
+
+    [connections.production]
+    host = "https://api.ntropii.com/v1"
+    api_key = "ntro_prod_key"
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import tomli_w
+
+from ntro.workspace.exceptions import ConfigError
+
+DEFAULT_HOST = "https://api.ntropii.com/v1"
+
+
+@dataclass
+class ConnectionConfig:
+    name: str
+    host: str = DEFAULT_HOST
+    api_key: str = ""
+    default_tenant: str | None = None
+    default_entity: str | None = None
+
+
+@dataclass
+class NtroConfig:
+    default_connection_name: str = "production"
+    connections: dict[str, ConnectionConfig] = field(default_factory=dict)
+
+    def get_connection(self, name: str | None = None) -> ConnectionConfig:
+        target = name or self.default_connection_name
+        if target not in self.connections:
+            raise ConfigError(
+                f"Connection '{target}' not found in config. "
+                f"Available: {list(self.connections.keys()) or ['(none)']}\n"
+                f"Run 'ntro auth login' to configure a connection."
+            )
+        return self.connections[target]
+
+
+def _config_path() -> Path:
+    ntro_home = os.environ.get("NTRO_HOME")
+    if ntro_home:
+        return Path(ntro_home) / "config.toml"
+    return Path.home() / ".ntro" / "config.toml"
+
+
+def load_config() -> NtroConfig:
+    """Load config from disk. Returns an empty config (production defaults) if missing."""
+    path = _config_path()
+    if not path.exists():
+        return NtroConfig(
+            default_connection_name="production",
+            connections={
+                "production": ConnectionConfig(
+                    name="production",
+                    host=DEFAULT_HOST,
+                    api_key="",
+                )
+            },
+        )
+
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    connections: dict[str, ConnectionConfig] = {}
+    for conn_name, conn_data in data.get("connections", {}).items():
+        connections[conn_name] = ConnectionConfig(
+            name=conn_name,
+            host=conn_data.get("host", DEFAULT_HOST),
+            api_key=conn_data.get("api_key", ""),
+            default_tenant=conn_data.get("default_tenant"),
+            default_entity=conn_data.get("default_entity"),
+        )
+
+    return NtroConfig(
+        default_connection_name=data.get("default_connection_name", "production"),
+        connections=connections,
+    )
+
+
+def save_config(config: NtroConfig) -> None:
+    """Write config back to disk."""
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict[str, object] = {
+        "default_connection_name": config.default_connection_name,
+        "connections": {},
+    }
+
+    conns: dict[str, dict[str, object]] = {}
+    for name, conn in config.connections.items():
+        entry: dict[str, object] = {"host": conn.host, "api_key": conn.api_key}
+        if conn.default_tenant:
+            entry["default_tenant"] = conn.default_tenant
+        if conn.default_entity:
+            entry["default_entity"] = conn.default_entity
+        conns[name] = entry
+
+    data["connections"] = conns
+
+    with open(path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def write_default_config() -> Path:
+    """Write the default config file (local + production connections) if it doesn't exist."""
+    path = _config_path()
+    if path.exists():
+        return path
+
+    config = NtroConfig(
+        default_connection_name="local",
+        connections={
+            "local": ConnectionConfig(
+                name="local",
+                host="http://localhost:3000/v1",
+                api_key="ntro_dev_key",
+            ),
+            "production": ConnectionConfig(
+                name="production",
+                host=DEFAULT_HOST,
+                api_key="",
+            ),
+        },
+    )
+    save_config(config)
+    return path