semblance-foundry 0.1.0__tar.gz

semblance_foundry-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Semblance Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT WITHOUT LIMITATION THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semblance_foundry-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: semblance-foundry
+Version: 0.1.0
+Summary: Unofficial local HTTP simulation of selected Palantir Foundry API v2 ontology operations
+Author: Semblance Contributors
+License-Expression: MIT
+Project-URL: Documentation, https://semblance.readthedocs.io/en/latest/guides/foundry/
+Project-URL: Repository, https://github.com/eddiethedean/semblance
+Project-URL: Changelog, https://github.com/eddiethedean/semblance/blob/main/packages/semblance-foundry/CHANGELOG.md
+Keywords: foundry,palantir,mock,simulation,testing,fastapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: semblance<0.8,>=0.6.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: ruff>=0.16.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Provides-Extra: sdk
+Requires-Dist: foundry-platform-sdk==1.101.0; extra == "sdk"
+Dynamic: license-file
+
+# semblance-foundry
+
+**Unofficial** local HTTP simulation of selected [Palantir Foundry API v2](https://www.palantir.com/docs/foundry/api/v2) ontology-read operations.
+
+This package is **not affiliated with, endorsed by, or equivalent to Palantir**. It does not implement Foundry's ontology engine, permissions, or compute. It is a test double for client development and CI.
+
+Verified against public API v2 documentation dated **2026-08-18**. See `compatibility.yaml` (also served at `/.well-known/foundry-mock-compatibility.json`).
+
+Requires `semblance` 0.6.1 or 0.7.x.
+
+## Install
+
+```bash
+pip install semblance-foundry
+```
+
+From a clone of this repository:
+
+```bash
+pip install -e ".[dev]"
+pip install -e "packages/semblance-foundry[dev]"
+```
+
+Optional official SDK extra (not installed in default CI):
+
+```bash
+pip install "semblance-foundry[sdk]"
+pytest packages/semblance-foundry/tests -m sdk
+```
+
+Pinned SDK: `foundry-platform-sdk==1.101.0`. Untested SDK versions are not implied compatible.
+
+## Quick start (HTTP)
+
+```python
+from semblance_foundry import FoundryMock, FoundryMockConfig
+from semblance_foundry.testing import foundry_test_client
+
+foundry = FoundryMock(FoundryMockConfig(seed=42, auth="optional"))
+foundry.load_bundled_fixture()
+client = foundry_test_client(foundry)
+
+r = client.get("/api/v2/ontologies/acme/objects/Employee?pageSize=2")
+assert r.status_code == 200
+```
+
+CLI:
+
+```bash
+semblance-foundry fixture init --output foundry.yaml
+semblance-foundry validate foundry.yaml
+semblance-foundry operations
+semblance-foundry serve --fixture foundry.yaml --port 8765
+# or: semblance-foundry serve   # bundled acme fixture
+```
+
+Environment variables for local clients (not Palantir credentials): `SEMBLANCE_FOUNDRY_HOST`, `SEMBLANCE_FOUNDRY_TOKEN`.
+
+## Auth modes
+
+- `disabled` — ignore `Authorization`
+- `optional` (default) — missing token is OK; malformed `Bearer` values return 401
+- `strict` — token must be in `FoundryMockConfig.tokens`
+
+Authentication errors never echo the token. This is not an OAuth server and does not validate real Palantir credentials.
+
+## Fixtures
+
+YAML/JSON version 1. Extra fields are rejected. Fixtures are **data only** — no expressions are evaluated. Register query callbacks in Python:
+
+```python
+foundry.register_query("employeesByOffice", lambda params, state: {"data": []})
+```
+
+`load_bundled_fixture()` loads the shipped `acme` example (one ontology, Employee + Office, `worksAt` links, `renameEmployee` action metadata, and `employeesByOffice` static query result). Use `load_fixture(path)` for your own files.
+
+## Pagination
+
+List endpoints use `pageSize` / `pageToken` / `nextPageToken`. Tokens are opaque and checksummed. Tampering or cross-resource reuse returns `InvalidPageToken` (400). Default page size 100, max 1000.
+
+## Known unsupported (0.1.0)
+
+- Action apply / applyBatch — `501 UnsupportedOperation` only when `auth=strict`; otherwise 404
+- Aggregates, object sets, datasets, transactions, orchestration, streams
+- Search filters other than `eq` and `and` of `eq` (400 `InvalidQuery`)
+
+Unknown paths return Foundry-style 404.
+
+## Compatibility matrix (MVP)
+
+| Level | Operations |
+|---|---|
+| exact | list/get ontologies, object types, objects, linked objects, action types (metadata), query types |
+| representative | object search (`eq`/`and`), query execute (static or callback) |
+| unsupported | apply, applyBatch |
+
+## Security
+
+- Do not put production secrets in fixtures or tokens used with this mock
+- Tokens are compared in-process and never written to error bodies
+- Query/action behavior must be allow-listed Python, never YAML eval
+
+## License
+
+MIT. Palantir and Foundry are trademarks of their respective owners.

semblance_foundry-0.1.0/README.md

@@ -0,0 +1,105 @@
+# semblance-foundry
+
+**Unofficial** local HTTP simulation of selected [Palantir Foundry API v2](https://www.palantir.com/docs/foundry/api/v2) ontology-read operations.
+
+This package is **not affiliated with, endorsed by, or equivalent to Palantir**. It does not implement Foundry's ontology engine, permissions, or compute. It is a test double for client development and CI.
+
+Verified against public API v2 documentation dated **2026-08-18**. See `compatibility.yaml` (also served at `/.well-known/foundry-mock-compatibility.json`).
+
+Requires `semblance` 0.6.1 or 0.7.x.
+
+## Install
+
+```bash
+pip install semblance-foundry
+```
+
+From a clone of this repository:
+
+```bash
+pip install -e ".[dev]"
+pip install -e "packages/semblance-foundry[dev]"
+```
+
+Optional official SDK extra (not installed in default CI):
+
+```bash
+pip install "semblance-foundry[sdk]"
+pytest packages/semblance-foundry/tests -m sdk
+```
+
+Pinned SDK: `foundry-platform-sdk==1.101.0`. Untested SDK versions are not implied compatible.
+
+## Quick start (HTTP)
+
+```python
+from semblance_foundry import FoundryMock, FoundryMockConfig
+from semblance_foundry.testing import foundry_test_client
+
+foundry = FoundryMock(FoundryMockConfig(seed=42, auth="optional"))
+foundry.load_bundled_fixture()
+client = foundry_test_client(foundry)
+
+r = client.get("/api/v2/ontologies/acme/objects/Employee?pageSize=2")
+assert r.status_code == 200
+```
+
+CLI:
+
+```bash
+semblance-foundry fixture init --output foundry.yaml
+semblance-foundry validate foundry.yaml
+semblance-foundry operations
+semblance-foundry serve --fixture foundry.yaml --port 8765
+# or: semblance-foundry serve   # bundled acme fixture
+```
+
+Environment variables for local clients (not Palantir credentials): `SEMBLANCE_FOUNDRY_HOST`, `SEMBLANCE_FOUNDRY_TOKEN`.
+
+## Auth modes
+
+- `disabled` — ignore `Authorization`
+- `optional` (default) — missing token is OK; malformed `Bearer` values return 401
+- `strict` — token must be in `FoundryMockConfig.tokens`
+
+Authentication errors never echo the token. This is not an OAuth server and does not validate real Palantir credentials.
+
+## Fixtures
+
+YAML/JSON version 1. Extra fields are rejected. Fixtures are **data only** — no expressions are evaluated. Register query callbacks in Python:
+
+```python
+foundry.register_query("employeesByOffice", lambda params, state: {"data": []})
+```
+
+`load_bundled_fixture()` loads the shipped `acme` example (one ontology, Employee + Office, `worksAt` links, `renameEmployee` action metadata, and `employeesByOffice` static query result). Use `load_fixture(path)` for your own files.
+
+## Pagination
+
+List endpoints use `pageSize` / `pageToken` / `nextPageToken`. Tokens are opaque and checksummed. Tampering or cross-resource reuse returns `InvalidPageToken` (400). Default page size 100, max 1000.
+
+## Known unsupported (0.1.0)
+
+- Action apply / applyBatch — `501 UnsupportedOperation` only when `auth=strict`; otherwise 404
+- Aggregates, object sets, datasets, transactions, orchestration, streams
+- Search filters other than `eq` and `and` of `eq` (400 `InvalidQuery`)
+
+Unknown paths return Foundry-style 404.
+
+## Compatibility matrix (MVP)
+
+| Level | Operations |
+|---|---|
+| exact | list/get ontologies, object types, objects, linked objects, action types (metadata), query types |
+| representative | object search (`eq`/`and`), query execute (static or callback) |
+| unsupported | apply, applyBatch |
+
+## Security
+
+- Do not put production secrets in fixtures or tokens used with this mock
+- Tokens are compared in-process and never written to error bodies
+- Query/action behavior must be allow-listed Python, never YAML eval
+
+## License
+
+MIT. Palantir and Foundry are trademarks of their respective owners.

semblance_foundry-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semblance-foundry"
+version = "0.1.0"
+description = "Unofficial local HTTP simulation of selected Palantir Foundry API v2 ontology operations"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Semblance Contributors"}]
+keywords = ["foundry", "palantir", "mock", "simulation", "testing", "fastapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "semblance>=0.6.1,<0.8",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "httpx>=0.25.0",
+    "ruff>=0.16.0",
+    "mypy>=1.0.0",
+    "types-PyYAML>=6.0.0",
+]
+sdk = [
+    "foundry-platform-sdk==1.101.0",
+]
+
+[project.scripts]
+semblance-foundry = "semblance_foundry.cli:main"
+
+[project.urls]
+Documentation = "https://semblance.readthedocs.io/en/latest/guides/foundry/"
+Repository = "https://github.com/eddiethedean/semblance"
+Changelog = "https://github.com/eddiethedean/semblance/blob/main/packages/semblance-foundry/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+semblance_foundry = [
+    "py.typed",
+    "compatibility.yaml",
+    "fixtures/defaults/*.yaml",
+]

semblance_foundry-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

semblance_foundry-0.1.0/src/semblance_foundry/__init__.py

@@ -0,0 +1,17 @@
+"""
+Unofficial local simulation of selected Palantir Foundry API v2 ontology operations.
+
+Not affiliated with, endorsed by, or equivalent to Palantir Foundry.
+"""
+
+from semblance_foundry.app import FoundryMock
+from semblance_foundry.config import FoundryMockConfig, TokenGrant
+from semblance_foundry.testing import FoundryMockContext, foundry_test_client
+
+__all__ = [
+    "FoundryMock",
+    "FoundryMockConfig",
+    "FoundryMockContext",
+    "TokenGrant",
+    "foundry_test_client",
+]

semblance_foundry-0.1.0/src/semblance_foundry/app.py

@@ -0,0 +1,89 @@
+"""FoundryMock factory and ASGI construction."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as pkg_version
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+
+from semblance_foundry.auth import FoundryMiddleware
+from semblance_foundry.compatibility import manifest_json
+from semblance_foundry.config import FoundryMockConfig
+from semblance_foundry.errors import register_exception_handlers
+from semblance_foundry.fixtures.loaders import (
+    apply_fixture,
+    bundled_acme_path,
+    load_fixture_file,
+)
+from semblance_foundry.ids import PageTokenCodec, rid_secret
+from semblance_foundry.services.ontologies import create_ontology_router
+from semblance_foundry.state import FoundryState, OntologyMutations
+
+_BUNDLED_FIXTURES = {"acme": bundled_acme_path}
+
+
+def _distribution_version() -> str:
+    try:
+        return pkg_version("semblance-foundry")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+class FoundryMock:
+    """Fixture-backed local simulation of selected Foundry API v2 operations."""
+
+    def __init__(self, config: FoundryMockConfig | None = None) -> None:
+        self.config = config or FoundryMockConfig()
+        self.state = FoundryState(seed=self.config.seed)
+        self.page_token_codec = PageTokenCodec(rid_secret(self.config.seed))
+        self._rng = random.Random(self.config.seed)
+        self.ontologies = OntologyMutations(self.state)
+
+    def load_fixture(self, path: str | Path) -> FoundryMock:
+        doc = load_fixture_file(path)
+        apply_fixture(doc, self.state)
+        return self
+
+    def load_bundled_fixture(self, name: str = "acme") -> FoundryMock:
+        """Load a fixture shipped with the package (currently ``acme``)."""
+        loader = _BUNDLED_FIXTURES.get(name)
+        if loader is None:
+            known = ", ".join(sorted(_BUNDLED_FIXTURES))
+            raise ValueError(
+                f"unknown bundled fixture {name!r}; expected one of: {known}"
+            )
+        return self.load_fixture(loader())
+
+    def register_query(self, api_name: str, fn: Callable[..., Any]) -> None:
+        """Register an allow-listed Python callback for query execute."""
+        self.state.register_query(api_name, fn)
+
+    def as_fastapi(self) -> FastAPI:
+        app = FastAPI(
+            title="semblance-foundry",
+            description=(
+                "Unofficial local simulation of selected Palantir Foundry "
+                "API v2 ontology operations. Not affiliated with Palantir."
+            ),
+            version=_distribution_version(),
+        )
+        app.state.foundry_mock = self
+        register_exception_handlers(app, self.config.seed)
+        app.add_middleware(
+            FoundryMiddleware,
+            config=self.config,
+            rng=self._rng,
+            error_counter={"n": 0},
+        )
+        app.include_router(create_ontology_router())
+
+        @app.get("/.well-known/foundry-mock-compatibility.json")
+        def compatibility() -> dict[str, Any]:
+            return manifest_json()
+
+        return app

semblance_foundry-0.1.0/src/semblance_foundry/auth.py

@@ -0,0 +1,167 @@
+"""Auth, request-id, latency, error injection, and rate-limit middleware."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections import defaultdict
+from collections.abc import Callable
+from threading import Lock
+from typing import Any
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from semblance_foundry.config import FoundryMockConfig
+from semblance_foundry.errors import foundry_error_body, next_error_instance_id
+
+REQUEST_ID_HEADER = "X-Request-ID"
+
+
+class _SlidingWindow:
+    def __init__(self) -> None:
+        self._timestamps: dict[tuple[str, str], list[float]] = defaultdict(list)
+        self._lock = Lock()
+
+    def allow(self, path: str, method: str, limit: float) -> bool:
+        if limit <= 0:
+            return True
+        now = time.monotonic()
+        key = (path, method)
+        with self._lock:
+            ts_list = self._timestamps[key]
+            ts_list[:] = [t for t in ts_list if now - t < 1.0]
+            if len(ts_list) >= limit:
+                return False
+            ts_list.append(now)
+        return True
+
+
+def _bearer_token(header: str | None) -> str | None:
+    if header is None or header == "":
+        return None
+    parts = header.split(None, 1)
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        raise ValueError("malformed")
+    token = parts[1].strip()
+    if not token:
+        raise ValueError("empty")
+    return token
+
+
+class FoundryMiddleware(BaseHTTPMiddleware):
+    """Auth, request-id, optional latency / error injection / rate limit."""
+
+    def __init__(
+        self,
+        app: Any,
+        config: FoundryMockConfig,
+        rng: random.Random,
+        error_counter: dict[str, int],
+    ) -> None:
+        super().__init__(app)
+        self._config = config
+        self._rng = rng
+        self._error_counter = error_counter
+        self._limiter = _SlidingWindow()
+
+    def _instance_id(self) -> str:
+        self._error_counter["n"] = self._error_counter.get("n", 0) + 1
+        return next_error_instance_id(
+            self._config.seed, self._error_counter["n"] + 10_000
+        )
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[[Request], Any]
+    ) -> Response:
+        incoming = request.headers.get(REQUEST_ID_HEADER)
+        request_id = incoming if incoming else f"req-{self._config.seed}-{id(request)}"
+        request.state.request_id = request_id
+
+        if self._config.rate_limit is not None:
+            if not self._limiter.allow(
+                request.url.path, request.method, self._config.rate_limit
+            ):
+                body = foundry_error_body(
+                    error_code="PERMISSION_DENIED",
+                    error_name="RateLimitExceeded",
+                    error_instance_id=self._instance_id(),
+                    parameters={},
+                )
+                response = JSONResponse(status_code=429, content=body)
+                response.headers[REQUEST_ID_HEADER] = request_id
+                return response
+
+        auth_error = self._check_auth(request)
+        if auth_error is not None:
+            auth_error.headers[REQUEST_ID_HEADER] = request_id
+            return auth_error
+
+        if self._config.latency_ms or self._config.jitter_ms:
+            delay = self._config.latency_ms / 1000.0
+            if self._config.jitter_ms:
+                delay += self._rng.uniform(0, self._config.jitter_ms) / 1000.0
+            if delay > 0:
+                await asyncio.sleep(delay)
+
+        if self._config.error_rate > 0 and self._rng.random() < self._config.error_rate:
+            codes = self._config.error_codes or [500]
+            status = self._rng.choice(codes)
+            body = foundry_error_body(
+                error_code="INTERNAL",
+                error_name="InjectedError",
+                error_instance_id=self._instance_id(),
+                parameters={"statusCode": status},
+            )
+            response = JSONResponse(status_code=status, content=body)
+            response.headers[REQUEST_ID_HEADER] = request_id
+            return response
+
+        response = await call_next(request)
+        response.headers[REQUEST_ID_HEADER] = request_id
+        return response  # type: ignore[no-any-return]
+
+    def _check_auth(self, request: Request) -> JSONResponse | None:
+        mode = self._config.auth
+        if mode == "disabled":
+            return None
+        header = request.headers.get("authorization")
+        try:
+            token = _bearer_token(header)
+        except ValueError:
+            return JSONResponse(
+                status_code=401,
+                content=foundry_error_body(
+                    error_code="UNAUTHORIZED",
+                    error_name="InvalidCredentials",
+                    error_instance_id=self._instance_id(),
+                    parameters={},
+                ),
+            )
+        if mode == "optional":
+            return None
+        # strict
+        if token is None:
+            return JSONResponse(
+                status_code=401,
+                content=foundry_error_body(
+                    error_code="UNAUTHORIZED",
+                    error_name="MissingCredentials",
+                    error_instance_id=self._instance_id(),
+                    parameters={},
+                ),
+            )
+        allowed = {g.token for g in self._config.tokens}
+        if token not in allowed:
+            return JSONResponse(
+                status_code=401,
+                content=foundry_error_body(
+                    error_code="UNAUTHORIZED",
+                    error_name="InvalidCredentials",
+                    error_instance_id=self._instance_id(),
+                    parameters={},
+                ),
+            )
+        return None