semblance-foundry 0.1.0__py3-none-any.whl

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/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/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

semblance_foundry/cli.py

@@ -0,0 +1,105 @@
+"""CLI: serve, validate, fixture init, operations."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from semblance_foundry.app import FoundryMock
+from semblance_foundry.config import FoundryMockConfig
+from semblance_foundry.fixtures.loaders import bundled_acme_path, load_fixture_file
+from semblance_foundry.registry import registered_operations
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    config = FoundryMockConfig(seed=args.seed, auth=args.auth)
+    mock = FoundryMock(config)
+    mock.load_fixture(args.fixture or bundled_acme_path())
+    app = mock.as_fastapi()
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise SystemExit(
+            "uvicorn not found. Install semblance (pulls uvicorn)."
+        ) from exc
+    uvicorn.run(app, host=args.host, port=args.port)
+
+
+def cmd_validate(args: argparse.Namespace) -> None:
+    try:
+        load_fixture_file(args.fixture)
+    except Exception as exc:
+        raise SystemExit(f"Invalid fixture: {exc}") from exc
+    print("OK")
+
+
+def cmd_fixture_init(args: argparse.Namespace) -> None:
+    dest = Path(args.output)
+    if dest.exists() and not args.force:
+        raise SystemExit(f"{dest} already exists (use --force to overwrite)")
+    dest.write_text(bundled_acme_path().read_text(encoding="utf-8"), encoding="utf-8")
+    print(f"Wrote {dest}")
+
+
+def cmd_operations(_args: argparse.Namespace) -> None:
+    rows = registered_operations()
+    width = max((len(op.operation_id) for op in rows), default=8)
+    print(f"{'operation':<{width}}  {'level':<16}  method  path")
+    for op in rows:
+        print(
+            f"{op.operation_id:<{width}}  {op.support_level:<16}  "
+            f"{op.method:<6}  {op.path}"
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="semblance-foundry",
+        description=(
+            "Unofficial local Foundry API v2 ontology mock. "
+            "Not affiliated with Palantir."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="Run a local mock server")
+    serve.add_argument(
+        "--fixture",
+        default=None,
+        help="YAML or JSON fixture path (default: bundled acme example)",
+    )
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8765)
+    serve.add_argument("--seed", type=int, default=42)
+    serve.add_argument(
+        "--auth",
+        default="optional",
+        choices=["disabled", "optional", "strict"],
+    )
+    serve.set_defaults(func=cmd_serve)
+
+    validate = sub.add_parser("validate", help="Validate a fixture without serving")
+    validate.add_argument("fixture")
+    validate.set_defaults(func=cmd_validate)
+
+    init = sub.add_parser("fixture", help="Fixture helpers")
+    init_sub = init.add_subparsers(dest="fixture_command", required=True)
+    init_cmd = init_sub.add_parser("init", help="Write the bundled example fixture")
+    init_cmd.add_argument("--output", required=True)
+    init_cmd.add_argument("--force", action="store_true")
+    init_cmd.set_defaults(func=cmd_fixture_init)
+
+    ops = sub.add_parser("operations", help="Print the compatibility table")
+    ops.set_defaults(func=cmd_operations)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

semblance_foundry/compatibility.py

@@ -0,0 +1,30 @@
+"""Load and publish the per-operation compatibility manifest."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_MANIFEST_PATH = Path(__file__).resolve().parent / "compatibility.yaml"
+
+
+@lru_cache(maxsize=1)
+def load_manifest() -> dict[str, Any]:
+    data = yaml.safe_load(_MANIFEST_PATH.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("compatibility.yaml must be a mapping")
+    return data
+
+
+def manifest_json() -> dict[str, Any]:
+    return load_manifest()
+
+
+def operations_table() -> list[dict[str, Any]]:
+    ops = load_manifest().get("operations", [])
+    if not isinstance(ops, list):
+        return []
+    return [op for op in ops if isinstance(op, dict)]

semblance_foundry/compatibility.yaml

@@ -0,0 +1,102 @@
+packageVersion: "0.1.0"
+documentedAt: "2026-08-18"
+source: "https://www.palantir.com/docs/foundry/api/v2"
+operations:
+  - operationId: ListOntologies
+    method: GET
+    path: /api/v2/ontologies
+    supportLevel: exact
+    docsUrl: https://www.palantir.com/docs/foundry/api/v2/ontologies-v2-resources/ontologies/list-ontologies
+    tests:
+      - tests/contract/test_ontologies.py::test_list_ontologies
+  - operationId: GetOntology
+    method: GET
+    path: /api/v2/ontologies/{ontology}
+    supportLevel: exact
+    docsUrl: https://www.palantir.com/docs/foundry/api/v2/ontologies-v2-resources/ontologies/get-ontology
+    tests:
+      - tests/contract/test_ontologies.py::test_get_ontology
+  - operationId: ListObjectTypes
+    method: GET
+    path: /api/v2/ontologies/{ontology}/objectTypes
+    supportLevel: exact
+    docsUrl: https://www.palantir.com/docs/foundry/api/v2/ontologies-v2-resources/object-types/list-object-types
+    tests:
+      - tests/contract/test_object_types.py::test_list_object_types
+  - operationId: GetObjectType
+    method: GET
+    path: /api/v2/ontologies/{ontology}/objectTypes/{objectType}
+    supportLevel: exact
+    tests:
+      - tests/contract/test_object_types.py::test_get_object_type
+  - operationId: ListObjects
+    method: GET
+    path: /api/v2/ontologies/{ontology}/objects/{objectType}
+    supportLevel: exact
+    docsUrl: https://www.palantir.com/docs/foundry/api/v2/ontologies-v2-resources/ontology-objects/list-objects
+    tests:
+      - tests/contract/test_objects.py::test_list_objects
+  - operationId: GetObject
+    method: GET
+    path: /api/v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}
+    supportLevel: exact
+    tests:
+      - tests/contract/test_objects.py::test_get_object
+  - operationId: SearchObjects
+    method: POST
+    path: /api/v2/ontologies/{ontology}/objects/{objectType}/search
+    supportLevel: representative
+    docsUrl: https://www.palantir.com/docs/foundry/api/v2/ontologies-v2-resources/ontology-objects/search-objects
+    notes: eq and and-of-eq filters only
+    tests:
+      - tests/contract/test_search.py::test_search_eq
+  - operationId: ListLinkedObjects
+    method: GET
+    path: /api/v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType}
+    supportLevel: exact
+    tests:
+      - tests/contract/test_links.py::test_list_linked_objects
+  - operationId: ListActionTypes
+    method: GET
+    path: /api/v2/ontologies/{ontology}/actionTypes
+    supportLevel: exact
+    notes: metadata only; apply is unimplemented
+    tests:
+      - tests/contract/test_actions_queries.py::test_list_action_types
+  - operationId: GetActionType
+    method: GET
+    path: /api/v2/ontologies/{ontology}/actionTypes/{actionType}
+    supportLevel: exact
+    tests:
+      - tests/contract/test_actions_queries.py::test_get_action_type
+  - operationId: ListQueryTypes
+    method: GET
+    path: /api/v2/ontologies/{ontology}/queryTypes
+    supportLevel: exact
+    tests:
+      - tests/contract/test_actions_queries.py::test_list_query_types
+  - operationId: GetQueryType
+    method: GET
+    path: /api/v2/ontologies/{ontology}/queryTypes/{queryApiName}
+    supportLevel: exact
+    tests:
+      - tests/contract/test_actions_queries.py::test_get_query_type
+  - operationId: ExecuteQuery
+    method: POST
+    path: /api/v2/ontologies/{ontology}/queries/{queryApiName}/execute
+    supportLevel: representative
+    notes: static fixture result or allow-listed Python callback
+    tests:
+      - tests/contract/test_actions_queries.py::test_execute_query
+  - operationId: ApplyAction
+    method: POST
+    path: /api/v2/ontologies/{ontology}/actions/{actionType}/apply
+    supportLevel: unsupported
+    tests:
+      - tests/contract/test_unsupported.py::test_apply_strict_501
+  - operationId: ApplyActionBatch
+    method: POST
+    path: /api/v2/ontologies/{ontology}/actions/{actionType}/applyBatch
+    supportLevel: unsupported
+    tests:
+      - tests/contract/test_unsupported.py::test_apply_batch_strict_501

semblance_foundry/config.py

@@ -0,0 +1,43 @@
+"""Typed configuration for FoundryMock."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+AuthMode = Literal["disabled", "optional", "strict"]
+
+
+@dataclass(frozen=True)
+class TokenGrant:
+    """A token accepted in strict auth mode. Never log or echo ``token``."""
+
+    token: str
+    scopes: tuple[str, ...] = ()
+
+
+@dataclass
+class FoundryMockConfig:
+    """Runtime options for a Foundry mock server."""
+
+    seed: int | None = 42
+    auth: AuthMode = "optional"
+    stateful: bool = True
+    tokens: tuple[TokenGrant, ...] = ()
+    error_rate: float = 0.0
+    error_codes: list[int] | None = None
+    latency_ms: float = 0.0
+    jitter_ms: float = 0.0
+    rate_limit: float | None = None
+    default_page_size: int = 100
+    max_page_size: int = 1000
+
+    def __post_init__(self) -> None:
+        if self.error_codes is None:
+            self.error_codes = [500]
+        if self.auth not in ("disabled", "optional", "strict"):
+            raise ValueError(
+                f"auth must be 'disabled', 'optional', or 'strict', got {self.auth!r}"
+            )
+        if not 0.0 <= self.error_rate <= 1.0:
+            raise ValueError("error_rate must be between 0 and 1")

semblance_foundry/errors.py

@@ -0,0 +1,131 @@
+"""Foundry-style error envelope and exception mapping."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+
+class FoundryError(Exception):
+    """Raised to produce a Foundry-compliant error response."""
+
+    def __init__(
+        self,
+        status_code: int,
+        error_code: str,
+        error_name: str,
+        parameters: dict[str, Any] | None = None,
+        error_instance_id: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        self.error_name = error_name
+        self.parameters = parameters or {}
+        self.error_instance_id = error_instance_id
+        super().__init__(error_name)
+
+    def to_body(self, instance_id: str) -> dict[str, Any]:
+        return {
+            "errorCode": self.error_code,
+            "errorName": self.error_name,
+            "errorInstanceId": instance_id,
+            "parameters": self.parameters,
+        }
+
+
+def next_error_instance_id(seed: int | None, counter: int) -> str:
+    """Deterministic errorInstanceId from seed + counter."""
+    return str(
+        uuid.uuid5(
+            uuid.NAMESPACE_URL,
+            f"semblance-foundry:error:{seed}:{counter}",
+        )
+    )
+
+
+def foundry_error_body(
+    *,
+    error_code: str,
+    error_name: str,
+    error_instance_id: str,
+    parameters: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {
+        "errorCode": error_code,
+        "errorName": error_name,
+        "errorInstanceId": error_instance_id,
+        "parameters": parameters or {},
+    }
+
+
+def register_exception_handlers(app: Any, seed: int | None) -> None:
+    """Attach Foundry JSON error handlers to a FastAPI app."""
+
+    counter = {"n": 0}
+
+    def _instance_id() -> str:
+        counter["n"] += 1
+        return next_error_instance_id(seed, counter["n"])
+
+    @app.exception_handler(FoundryError)
+    async def foundry_error_handler(
+        request: Request, exc: FoundryError
+    ) -> JSONResponse:
+        instance_id = exc.error_instance_id or _instance_id()
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=exc.to_body(instance_id),
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_handler(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=400,
+            content=foundry_error_body(
+                error_code="INVALID_ARGUMENT",
+                error_name="InvalidArgument",
+                error_instance_id=_instance_id(),
+                parameters={"errors": exc.errors()},
+            ),
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def http_exception_handler(
+        request: Request, exc: StarletteHTTPException
+    ) -> JSONResponse:
+        if exc.status_code == 404:
+            return JSONResponse(
+                status_code=404,
+                content=foundry_error_body(
+                    error_code="NOT_FOUND",
+                    error_name="NotFound",
+                    error_instance_id=_instance_id(),
+                    parameters={"path": str(request.url.path)},
+                ),
+            )
+        if exc.status_code == 405:
+            return JSONResponse(
+                status_code=405,
+                content=foundry_error_body(
+                    error_code="INVALID_ARGUMENT",
+                    error_name="MethodNotAllowed",
+                    error_instance_id=_instance_id(),
+                    parameters={"path": str(request.url.path)},
+                ),
+            )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=foundry_error_body(
+                error_code="UNKNOWN",
+                error_name="HttpException",
+                error_instance_id=_instance_id(),
+                parameters={},
+            ),
+        )