Jrm/can create model ingestion (#486)

* Add `canCreateModelIngestion` model permission check

* format

* oops

.github/workflows/pr.yml

@@ -9,8 +9,8 @@ on:
       - "main"
 
 jobs:
-  test:
-    name: test
+  test-internal: # Run integration tests against the internal server image
+    name: Test (internal)
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -20,6 +20,55 @@ jobs:
           - "3.12"
           - "3.13"
 
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: "ghcr.io"
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Run Speckle Server
+        run: docker compose --file docker-compose-internal.yml up --detach --wait
+
+      - name: Run tests
+        run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
+
+      - uses: codecov/codecov-action@v5
+        if: matrix.python-version == 3.12
+        with:
+          fail_ci_if_error: true # optional (default = false)
+          files: ./reports/test-results.xml # optional
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+  test-public: # Run integration tests against the public server image
+    name: Test (public)
+    runs-on: ubuntu-latest
+    env:
+      IS_PUBLIC: "true"
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
     steps:
       - uses: actions/checkout@v4
 
@@ -42,17 +91,10 @@ jobs:
         run: uv run pre-commit run --all-files
 
       - name: Run Speckle Server
-        run: docker compose up --detach --wait
+        run: docker compose --file docker-compose.yml up --detach --wait
 
       - name: Run tests
         run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
 
-      - uses: codecov/codecov-action@v5
-        if: matrix.python-version == 3.12
-        with:
-          fail_ci_if_error: true # optional (default = false)
-          files: ./reports/test-results.xml # optional
-          token: ${{ secrets.CODECOV_TOKEN }}
-
       - name: Minimize uv cache
         run: uv cache prune --ci

codebook.toml

@@ -0,0 +1 @@
+words = ["specklepy"]

docker-compose-internal.yml

@@ -0,0 +1,115 @@
+name: "speckle-server"
+
+services:
+  ####
+  # Speckle Server dependencies
+  #######
+  postgres:
+    image: "postgres:16.4-alpine3.20@sha256:d898b0b78a2627cb4ee63464a14efc9d296884f1b28c841b0ab7d7c42f1fffdf"
+    restart: always
+    environment:
+      POSTGRES_DB: speckle
+      POSTGRES_USER: speckle
+      POSTGRES_PASSWORD: speckle
+    volumes:
+      - ./.volumes/postgres-data:/var/lib/postgresql/data/
+    healthcheck:
+      # the -U user has to match the POSTGRES_USER value
+      test: ["CMD-SHELL", "pg_isready -U speckle"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  redis:
+    image: "valkey/valkey:8.1-alpine@sha256:0d27f0bca0249f61d060029a6aaf2e16b2c417d68d02a508e1dfb763fa2948b4"
+    restart: always
+    volumes:
+      - ./.volumes/redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  minio:
+    image: "minio/minio:RELEASE.2023-10-25T06-33-25Z"
+    command: server /data --console-address ":9001"
+    restart: always
+    volumes:
+      - ./.volumes/minio-data:/data
+    ports:
+      - '127.0.0.1:9000:9000'
+      - '127.0.0.1:9001:9001'
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "curl -s -o /dev/null http://127.0.0.1:9000/minio/index.html",
+        ]
+      interval: 5s
+      timeout: 30s
+      retries: 30
+      start_period: 10s
+
+  speckle-server:
+    image: ghcr.io/specklesystems/speckle-server:latest
+    restart: always
+    healthcheck:
+      test:
+        - CMD
+        - /nodejs/bin/node
+        - -e
+        - "try { require('node:http').request({headers: {'Content-Type': 'application/json'}, port:3000, hostname:'127.0.0.1', path:'/readiness', method: 'GET', timeout: 2000 }, (res) => { body = ''; res.on('data', (chunk) => {body += chunk;}); res.on('end', () => {process.exit(Number(res.statusCode != 200 || body.toLowerCase().includes('error')));}); }).end(); } catch { process.exit(1); }"
+      interval: 10s
+      timeout: 10s
+      retries: 3
+      start_period: 90s
+    ports:
+      - "0.0.0.0:3000:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    environment:
+      # TODO: Change this to the URL of the speckle server, as accessed from the network
+      CANONICAL_URL: "http://127.0.0.1:8080"
+      SPECKLE_AUTOMATE_URL: "http://127.0.0.1:3030"
+      FRONTEND_ORIGIN: "http://127.0.0.1:8081"
+
+      # TODO: Change thvolumes:
+      REDIS_URL: "redis://redis"
+
+      S3_ENDPOINT: "http://minio:9000"
+      S3_PUBLIC_ENDPOINT: "http://127.0.0.1:9000"
+      S3_ACCESS_KEY: "minioadmin"
+      S3_SECRET_KEY: "minioadmin"
+      S3_BUCKET: "speckle-server"
+      S3_CREATE_BUCKET: "true"
+
+      FILE_SIZE_LIMIT_MB: 100
+      MAX_PROJECT_MODELS_PER_PAGE: 500
+
+      # TODO: Change this to a unique secret for this server
+      SESSION_SECRET: "TODO:ReplaceWithLongString"
+
+      STRATEGY_LOCAL: "true"
+
+      POSTGRES_URL: 'postgres://speckle:speckle@postgres:5432/speckle'
+      ENABLE_MP: "false"
+
+      LOG_PRETTY: "true"
+
+      FF_NEXT_GEN_FILE_IMPORTER_ENABLED: "true"
+      FF_LARGE_FILE_IMPORTS_ENABLED: "true"
+
+networks:
+  default:
+    name: speckle-server
+
+volumes:
+  postgres-data:
+  redis-data:
+  minio-data:

docker-compose.yml

@@ -1,4 +1,3 @@
-version: "3.9"
 name: "speckle-server"
 
 services:
@@ -22,7 +21,7 @@ services:
       retries: 30
 
   redis:
-    image: "redis:6.0-alpine"
+    image: "valkey/valkey:8.1-alpine@sha256:0d27f0bca0249f61d060029a6aaf2e16b2c417d68d02a508e1dfb763fa2948b4"
     restart: always
     volumes:
       - ./.volumes/redis-data:/data
@@ -38,6 +37,9 @@ services:
     restart: always
     volumes:
       - ./.volumes/minio-data:/data
+    ports:
+      - '127.0.0.1:9000:9000'
+      - '127.0.0.1:9001:9001'
     healthcheck:
       test:
         [
@@ -48,8 +50,6 @@ services:
       timeout: 30s
       retries: 30
       start_period: 10s
-    ports:
-      - "0.0.0.0:9000:9000"
 
   speckle-server:
     image: speckle/speckle-server:latest
@@ -96,7 +96,6 @@ services:
       SESSION_SECRET: "TODO:ReplaceWithLongString"
 
       STRATEGY_LOCAL: "true"
-      DEBUG: "speckle:*"
 
       POSTGRES_URL: "postgres"
       POSTGRES_USER: "speckle"
@@ -104,9 +103,10 @@ services:
       POSTGRES_DB: "speckle"
       ENABLE_MP: "false"
 
+      LOG_PRETTY: "true"
+
       FF_NEXT_GEN_FILE_IMPORTER_ENABLED: "true"
       FF_LARGE_FILE_IMPORTS_ENABLED: "true"
-      FF_BACKGROUND_JOBS_ENABLED: "true"
 
 networks:
   default:

docs/index.md

@@ -0,0 +1,50 @@
+# specklepy API Reference
+
+> The Python SDK for Speckle - Build powerful AEC data workflows
+
+**specklepy** is the Python SDK for Speckle, enabling you to interact with Speckle Server, send and receive geometry, and build custom integrations for the AEC industry.
+
+## What is specklepy?
+
+specklepy is a comprehensive Python library that provides:
+
+* **Object-based data exchange** - Send and receive geometry and BIM data without files
+* **GraphQL API client** - Full access to Speckle Server's API
+* **Extensible object model** - Create custom objects that inherit from `Base`
+* **Multiple transport options** - Store data locally (SQLite), in-memory, or on Speckle Server
+* **Geometry support** - Rich geometric primitives (Point, Line, Mesh, etc.)
+
+## Speckle Automate
+
+Speckle Automate is a fully fledged CI/CD platform designed to run custom code on Speckle models whenever a new version is available.
+
+As a software developer, you can develop Functions that others in your team consume in Automations. From creating reports to running code compliance checks to wind simulations, there is no limit to what you can do with Automate.
+
+## Installation
+
+Install specklepy using pip:
+
+```bash
+pip install specklepy
+```
+
+## Quick Example
+
+```python
+from specklepy.api.client import SpeckleClient
+from specklepy.api.credentials import get_default_account
+from specklepy.objects.geometry import Point
+
+# Authenticate
+client = SpeckleClient(host="https://app.speckle.systems")
+account = get_default_account()
+client.authenticate_with_account(account)
+
+# Create geometry
+point = Point(x=10, y=20, z=5)
+```
+
+## Getting Help
+
+- **Community Forum**: [speckle.community](https://speckle.community/c/help/developers)
+- **GitHub Issues**: [github.com/specklesystems/specklepy](https://github.com/specklesystems/specklepy/issues)

docs/speckle_automate/automation_context.md

@@ -0,0 +1 @@
+::: speckle_automate.AutomationContext

docs/speckle_automate/runner.md

@@ -0,0 +1,3 @@
+::: speckle_automate.runner.execute_automate_function
+
+::: speckle_automate.runner.run_function

docs/speckle_automate/schema.md

@@ -0,0 +1,11 @@
+::: speckle_automate.AutomateBase
+
+::: speckle_automate.AutomationRunData
+
+::: speckle_automate.AutomationResult
+
+::: speckle_automate.ResultCase
+
+::: speckle_automate.AutomationStatus
+
+::: speckle_automate.ObjectResultLevel

docs/specklepy/api/client.md

@@ -0,0 +1 @@
+::: specklepy.api.client.SpeckleClient

docs/specklepy/api/credentials.md

@@ -0,0 +1,5 @@
+::: specklepy.api.credentials.Account
+
+::: specklepy.api.credentials.UserInfo
+
+::: specklepy.api.credentials.StreamWrapper

docs/specklepy/api/operations.md

@@ -0,0 +1,7 @@
+::: specklepy.api.operations.send
+
+::: specklepy.api.operations.receive
+
+::: specklepy.api.operations.serialize
+
+::: specklepy.api.operations.deserialize

docs/specklepy/api/resources/ActiveUserResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.ActiveUserResource

docs/specklepy/api/resources/FileImportResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.FileImportResource

docs/specklepy/api/resources/ModelResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.ModelResource

docs/specklepy/api/resources/OtherUserResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.OtherUserResource

docs/specklepy/api/resources/ProjectInviteResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.ProjectInviteResource

docs/specklepy/api/resources/ProjectResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.ProjectResource

docs/specklepy/api/resources/ServerResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.ServerResource

docs/specklepy/api/resources/SubscriptionResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.SubscriptionResource

docs/specklepy/api/resources/VersionResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.VersionResource

docs/specklepy/api/resources/WorkspaceResource.md

@@ -0,0 +1 @@
+::: specklepy.api.resources.WorkspaceResource

docs/specklepy/core/api/enums.md

@@ -0,0 +1 @@
+::: specklepy.core.api.enums.ProjectVisibility

docs/specklepy/core/api/inputs/inputs.md

@@ -0,0 +1,11 @@
+::: specklepy.core.api.inputs.ProjectCreateInput
+
+::: specklepy.core.api.inputs.ProjectUpdateInput
+
+::: specklepy.core.api.inputs.CreateModelInput
+
+::: specklepy.core.api.inputs.UpdateModelInput
+
+::: specklepy.core.api.inputs.CreateVersionInput
+
+::: specklepy.core.api.inputs.UpdateVersionInput

docs/specklepy/core/api/models/models.md

@@ -0,0 +1,13 @@
+::: specklepy.core.api.models.User
+
+::: specklepy.core.api.models.LimitedUser
+
+::: specklepy.core.api.models.ServerInfo
+
+::: specklepy.core.api.models.Project
+
+::: specklepy.core.api.models.Model
+
+::: specklepy.core.api.models.Version
+
+::: specklepy.core.api.models.current.Workspace

docs/specklepy/logging/exceptions.md

@@ -0,0 +1,7 @@
+::: specklepy.logging.exceptions.SpeckleException
+
+::: specklepy.logging.exceptions.GraphQLException
+
+::: specklepy.logging.exceptions.SerializationException
+
+::: specklepy.logging.exceptions.SpeckleWarning

docs/specklepy/objects/base.md

@@ -0,0 +1,3 @@
+::: specklepy.objects.Base
+
+::: specklepy.objects.base.DataChunk

docs/specklepy/objects/data_objects.md

@@ -0,0 +1,5 @@
+::: specklepy.objects.DataObject
+
+::: specklepy.objects.QgisObject
+
+::: specklepy.objects.BlenderObject

docs/specklepy/objects/geometry/Arc.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Arc

docs/specklepy/objects/geometry/Box.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Box

docs/specklepy/objects/geometry/Circle.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Circle

docs/specklepy/objects/geometry/ControlPoint.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.ControlPoint

docs/specklepy/objects/geometry/Curve.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Curve

docs/specklepy/objects/geometry/Ellipse.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Ellipse

docs/specklepy/objects/geometry/Line.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Line

docs/specklepy/objects/geometry/Mesh.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Mesh

docs/specklepy/objects/geometry/Plane.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Plane

docs/specklepy/objects/geometry/Point.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Point

docs/specklepy/objects/geometry/PointCloud.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.PointCloud

docs/specklepy/objects/geometry/Polycurve.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Polycurve

docs/specklepy/objects/geometry/Polyline.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Polyline

docs/specklepy/objects/geometry/Spiral.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Spiral

docs/specklepy/objects/geometry/Surface.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Surface

docs/specklepy/objects/geometry/Vector.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.Vector

docs/specklepy/objects/graph_traversal/traversal.md

@@ -0,0 +1,7 @@
+::: specklepy.objects.graph_traversal.GraphTraversal
+
+::: specklepy.objects.graph_traversal.TraversalContext
+
+::: specklepy.objects.graph_traversal.TraversalRule
+
+::: specklepy.objects.graph_traversal.DefaultRule

docs/specklepy/objects/other/collection.md

@@ -0,0 +1 @@
+::: specklepy.objects.models.collections.collection.Collection

docs/specklepy/objects/other/render_material.md

@@ -0,0 +1 @@
+::: specklepy.objects.other.RenderMaterial

docs/specklepy/objects/primitives/interval.md

@@ -0,0 +1 @@
+::: specklepy.objects.primitive.Interval

docs/specklepy/objects/proxies/ColorProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.ColorProxy

docs/specklepy/objects/proxies/GroupProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.GroupProxy

docs/specklepy/objects/proxies/InstanceDefinitionProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.InstanceDefinitionProxy

docs/specklepy/objects/proxies/InstanceProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.InstanceProxy

docs/specklepy/objects/proxies/LevelProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.LevelProxy

docs/specklepy/objects/proxies/RenderMaterialProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.RenderMaterialProxy

docs/specklepy/serialization/serializer.md

@@ -0,0 +1 @@
+::: specklepy.serialization.base_object_serializer.BaseObjectSerializer

docs/specklepy/transports/transports.md

@@ -0,0 +1,7 @@
+::: specklepy.transports.abstract_transport.AbstractTransport
+
+::: specklepy.transports.memory.MemoryTransport
+
+::: specklepy.transports.sqlite.SQLiteTransport
+
+::: specklepy.transports.server.ServerTransport

docs/stylesheets/extra.css

@@ -0,0 +1,304 @@
+.md-content h1 {
+    font-size: 1.125rem;
+    font-weight: 700;
+    color: #111827;
+    letter-spacing: -0.025em;
+    line-height: 1.2;
+}
+
+@media (min-width: 640px) {
+    .md-content h1 {
+        font-size: 1.25rem;
+    }
+}
+
+[data-md-color-scheme="slate"] .md-content h1 {
+    color: #e5e7eb;
+}
+
+.md-content h2 {
+    font-size: 1rem;
+    font-weight: 700;
+    color: #111827;
+    letter-spacing: -0.025em;
+    margin-top: 2rem;
+}
+
+@media (min-width: 640px) {
+    .md-content h2 {
+        font-size: 1.125rem;
+    }
+}
+
+[data-md-color-scheme="slate"] .md-content h2 {
+    color: #e5e7eb;
+}
+
+.md-content h3 {
+    font-size: 0.9375rem;
+    font-weight: 600;
+    color: #1f2937;
+    margin-top: 1.5rem;
+}
+
+@media (min-width: 640px) {
+    .md-content h3 {
+        font-size: 1rem;
+    }
+}
+
+[data-md-color-scheme="slate"] .md-content h3 {
+    color: #d1d5db;
+}
+
+.md-content p,
+.md-content li {
+    font-size: 0.875rem;
+    line-height: 1.6;
+    color: #374151;
+    margin-top: 0.5rem;
+}
+
+[data-md-color-scheme="slate"] .md-content p,
+[data-md-color-scheme="slate"] .md-content li {
+    color: #d1d5db;
+}
+
+.doc.doc-object-name {
+    font-size: 1.125rem;
+    font-weight: 700;
+    color: #111827;
+}
+
+[data-md-color-scheme="slate"] .doc.doc-object-name {
+    color: #e5e7eb;
+}
+
+.doc.doc-heading {
+    font-size: 0.9375rem;
+    font-weight: 600;
+    color: #1f2937;
+}
+
+[data-md-color-scheme="slate"] .doc.doc-heading {
+    color: #d1d5db;
+}
+
+.md-content code {
+    font-size: 0.75rem;
+    color: #dc2626;
+    background-color: #f3f4f6;
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+}
+
+[data-md-color-scheme="slate"] .md-content code {
+    color: #fca5a5;
+    background-color: #1f2937;
+}
+
+.md-content pre code {
+    font-size: 0.75rem;
+    color: inherit;
+    background-color: transparent;
+    padding: 0;
+}
+
+.md-content a {
+    color: #2563eb;
+    text-decoration: none;
+}
+
+.md-content a:hover {
+    color: #1d4ed8;
+    text-decoration: underline;
+}
+
+[data-md-color-scheme="slate"] .md-content a {
+    color: #60a5fa;
+}
+
+[data-md-color-scheme="slate"] .md-content a:hover {
+    color: #93c5fd;
+}
+
+[data-md-color-scheme="slate"] {
+    --md-default-bg-color: #000000;
+    --md-default-fg-color: #ffffff;
+    --md-code-bg-color: #0a0a0a;
+    --md-code-fg-color: #ffffff;
+}
+
+[data-md-color-scheme="slate"] .md-header {
+    background-color: #000000;
+}
+
+[data-md-color-scheme="slate"] .md-tabs {
+    background-color: #000000;
+}
+
+[data-md-color-scheme="slate"] .md-footer {
+    background-color: #000000;
+}
+
+[data-md-color-scheme="slate"] .md-sidebar {
+    background-color: #000000;
+}
+
+[data-md-color-scheme="slate"] .md-nav {
+    background-color: #000000;
+}
+
+.highlight pre,
+.highlight code {
+    background-color: #f6f8fa !important;
+    color: #24292e !important;
+}
+
+.highlight .k,
+.highlight .kc,
+.highlight .kd,
+.highlight .kn,
+.highlight .kp,
+.highlight .kr,
+.highlight .kt {
+    color: #d73a49 !important;
+}
+
+.highlight .s,
+.highlight .s1,
+.highlight .s2,
+.highlight .sb,
+.highlight .sc,
+.highlight .sd,
+.highlight .se,
+.highlight .sh,
+.highlight .si,
+.highlight .sx,
+.highlight .sr,
+.highlight .ss {
+    color: #032f62 !important;
+}
+
+.highlight .nf,
+.highlight .fm,
+.highlight .nc {
+    color: #6f42c1 !important;
+}
+
+.highlight .m,
+.highlight .mf,
+.highlight .mh,
+.highlight .mi,
+.highlight .mo {
+    color: #005cc5 !important;
+}
+
+.highlight .c,
+.highlight .c1,
+.highlight .cm,
+.highlight .cp,
+.highlight .cs {
+    color: #6a737d !important;
+    font-style: italic;
+}
+
+.highlight .o,
+.highlight .ow {
+    color: #d73a49 !important;
+}
+
+.highlight .n,
+.highlight .na,
+.highlight .nb,
+.highlight .nd,
+.highlight .ni,
+.highlight .nl,
+.highlight .nn,
+.highlight .nx,
+.highlight .py,
+.highlight .nt,
+.highlight .nv,
+.highlight .bp,
+.highlight .vc,
+.highlight .vg,
+.highlight .vi {
+    color: #e36209 !important;
+}
+
+[data-md-color-scheme="slate"] .highlight pre,
+[data-md-color-scheme="slate"] .highlight code {
+    background-color: #0d1117 !important;
+    color: #e6edf3 !important;
+}
+
+[data-md-color-scheme="slate"] .highlight .k,
+[data-md-color-scheme="slate"] .highlight .kc,
+[data-md-color-scheme="slate"] .highlight .kd,
+[data-md-color-scheme="slate"] .highlight .kn,
+[data-md-color-scheme="slate"] .highlight .kp,
+[data-md-color-scheme="slate"] .highlight .kr,
+[data-md-color-scheme="slate"] .highlight .kt {
+    color: #ff7b72 !important;
+}
+
+[data-md-color-scheme="slate"] .highlight .s,
+[data-md-color-scheme="slate"] .highlight .s1,
+[data-md-color-scheme="slate"] .highlight .s2,
+[data-md-color-scheme="slate"] .highlight .sb,
+[data-md-color-scheme="slate"] .highlight .sc,
+[data-md-color-scheme="slate"] .highlight .sd,
+[data-md-color-scheme="slate"] .highlight .se,
+[data-md-color-scheme="slate"] .highlight .sh,
+[data-md-color-scheme="slate"] .highlight .si,
+[data-md-color-scheme="slate"] .highlight .sx,
+[data-md-color-scheme="slate"] .highlight .sr,
+[data-md-color-scheme="slate"] .highlight .ss {
+    color: #a5d6ff !important;
+}
+
+[data-md-color-scheme="slate"] .highlight .nf,
+[data-md-color-scheme="slate"] .highlight .fm,
+[data-md-color-scheme="slate"] .highlight .nc {
+    color: #d2a8ff !important;
+}
+
+[data-md-color-scheme="slate"] .highlight .m,
+[data-md-color-scheme="slate"] .highlight .mf,
+[data-md-color-scheme="slate"] .highlight .mh,
+[data-md-color-scheme="slate"] .highlight .mi,
+[data-md-color-scheme="slate"] .highlight .mo {
+    color: #79c0ff !important;
+}
+
+[data-md-color-scheme="slate"] .highlight .c,
+[data-md-color-scheme="slate"] .highlight .c1,
+[data-md-color-scheme="slate"] .highlight .cm,
+[data-md-color-scheme="slate"] .highlight .cp,
+[data-md-color-scheme="slate"] .highlight .cs {
+    color: #8b949e !important;
+    font-style: italic;
+}
+
+[data-md-color-scheme="slate"] .highlight .o,
+[data-md-color-scheme="slate"] .highlight .ow {
+    color: #ff7b72 !important;
+}
+
+[data-md-color-scheme="slate"] .highlight .n,
+[data-md-color-scheme="slate"] .highlight .na,
+[data-md-color-scheme="slate"] .highlight .nb,
+[data-md-color-scheme="slate"] .highlight .nd,
+[data-md-color-scheme="slate"] .highlight .ni,
+[data-md-color-scheme="slate"] .highlight .nl,
+[data-md-color-scheme="slate"] .highlight .nn,
+[data-md-color-scheme="slate"] .highlight .nx,
+[data-md-color-scheme="slate"] .highlight .py,
+[data-md-color-scheme="slate"] .highlight .nt,
+[data-md-color-scheme="slate"] .highlight .nv,
+[data-md-color-scheme="slate"] .highlight .bp,
+[data-md-color-scheme="slate"] .highlight .vc,
+[data-md-color-scheme="slate"] .highlight .vg,
+[data-md-color-scheme="slate"] .highlight .vi {
+    color: #ffa657 !important;
+}

mise.toml

@@ -1,6 +1,27 @@
 [tools]
 python = "3.13.7"
+uv = "0.9.11"
 
 [settings]
 experimental = true
 python.uv_venv_auto = true
+
+
+[tasks.install]
+run= "uv sync --all-extras --all-groups"
+
+
+[tasks.install_docs]
+run= "uv sync --group docs"
+
+[tasks.build_docs]
+description = "Build static docs "
+run = "uv run mkdocs build"
+depends = ['install_docs']
+
+[tasks.test]
+run = "uv run pytest"
+
+
+[env]
+IS_PUBLIC = "false"

mkdocs.yml

@@ -0,0 +1,130 @@
+site_name: specklepy Docs
+theme:
+  name: material
+  font:
+    text: Inter
+  favicon: assets/speckle_logo.png
+  logo: assets/speckle_logo.png
+  features:
+    - navigation.tabs
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: white
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: black
+      logo: assets/logo_white.png
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+extra_css:
+- stylesheets/extra.css
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            parameter_headings: false
+            members_order: source
+            separate_signature: true
+            filters: ["!^_"] #Ignore _ prefixed properties
+            docstring_options:
+              ignore_init_summary: true
+            merge_init_into_class: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            show_if_no_docstring: true
+            show_labels: true
+            show_source: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            show_bases: false
+            heading_level: 3
+
+          inventories:
+            - url: https://docs.python.org/3/objects.inv
+              domains: [py, std]
+
+nav:
+  - Home: index.md
+  - specklepy SDK:
+    - API:
+      - Client: specklepy/api/client.md
+      - Credentials: specklepy/api/credentials.md
+      - Operations: specklepy/api/operations.md
+      - Resources:
+        - ActiveUserResource: specklepy/api/resources/ActiveUserResource.md
+        - FileImportResource: specklepy/api/resources/FileImportResource.md
+        - ModelResource: specklepy/api/resources/ModelResource.md
+        - OtherUserResource: specklepy/api/resources/OtherUserResource.md
+        - ProjectInviteResource: specklepy/api/resources/ProjectInviteResource.md
+        - ProjectResource: specklepy/api/resources/ProjectResource.md
+        - ServerResource: specklepy/api/resources/ServerResource.md
+        - SubscriptionResource: specklepy/api/resources/SubscriptionResource.md
+        - VersionResource: specklepy/api/resources/VersionResource.md
+        - WorkspaceResource: specklepy/api/resources/WorkspaceResource.md
+    - Objects:
+      - Base: specklepy/objects/base.md
+      - Data Objects: specklepy/objects/data_objects.md
+      - Geometry:
+        - Arc: specklepy/objects/geometry/Arc.md
+        - Box: specklepy/objects/geometry/Box.md
+        - Circle: specklepy/objects/geometry/Circle.md
+        - ControlPoint: specklepy/objects/geometry/ControlPoint.md
+        - Curve: specklepy/objects/geometry/Curve.md
+        - Ellipse: specklepy/objects/geometry/Ellipse.md
+        - Line: specklepy/objects/geometry/Line.md
+        - Mesh: specklepy/objects/geometry/Mesh.md
+        - Plane: specklepy/objects/geometry/Plane.md
+        - Point: specklepy/objects/geometry/Point.md
+        - PointCloud: specklepy/objects/geometry/PointCloud.md
+        - Polycurve: specklepy/objects/geometry/Polycurve.md
+        - Polyline: specklepy/objects/geometry/Polyline.md
+        - Spiral: specklepy/objects/geometry/Spiral.md
+        - Surface: specklepy/objects/geometry/Surface.md
+        - Vector: specklepy/objects/geometry/Vector.md
+      - Primitives:
+        - Interval: specklepy/objects/primitives/interval.md
+      - Other:
+        - RenderMaterial: specklepy/objects/other/render_material.md
+        - Collection: specklepy/objects/other/collection.md
+      - Proxies:
+        - ColorProxy: specklepy/objects/proxies/ColorProxy.md
+        - GroupProxy: specklepy/objects/proxies/GroupProxy.md
+        - InstanceProxy: specklepy/objects/proxies/InstanceProxy.md
+        - InstanceDefinitionProxy: specklepy/objects/proxies/InstanceDefinitionProxy.md
+        - LevelProxy: specklepy/objects/proxies/LevelProxy.md
+        - RenderMaterialProxy: specklepy/objects/proxies/RenderMaterialProxy.md
+      - Graph Traversal: specklepy/objects/graph_traversal/traversal.md
+    - Transports: specklepy/transports/transports.md
+    - Serialization: specklepy/serialization/serializer.md
+    - Core API:
+      - Models: specklepy/core/api/models/models.md
+      - Inputs: specklepy/core/api/inputs/inputs.md
+      - Enums: specklepy/core/api/enums.md
+    - Logging:
+      - Exceptions: specklepy/logging/exceptions.md
+  - Speckle Automate:
+    - AutomationContext: speckle_automate/automation_context.md
+    - Runner: speckle_automate/runner.md
+    - Schema: speckle_automate/schema.md

netlify.toml

@@ -0,0 +1,3 @@
+[build]
+  command = "mise run build_docs"
+  publish = "site"

pyproject.toml

@@ -11,7 +11,7 @@ dependencies = [
     "appdirs>=1.4.4",
     "attrs>=24.3.0",
     "deprecated>=1.2.15",
-    "gql[requests,websockets]>=3.5.0",
+    "gql[requests,websockets]>=3.5.0,<4.0.0",
     "httpx>=0.28.1",
     "pydantic>=2.10.5",
     "pydantic-settings>=2.7.1",
@@ -22,6 +22,7 @@ dependencies = [
 speckleifc = ["ifcopenshell>=0.8.3.post2"]
 
 [dependency-groups]
+
 dev = [
     "commitizen>=4.1.0",
     "devtools>=0.12.2",
@@ -32,11 +33,18 @@ dev = [
     "pytest-asyncio>=0.25.2",
     "pytest-cov>=6.0.0",
     "pytest-ordering>=0.6",
-    "ruff>=0.9.2",
+    "pytest_httpserver >=1.1.3",
+    "ruff==0.9.2",
     "types-deprecated>=1.2.15.20241117",
     "types-requests>=2.32.0.20241016",
     "types-ujson>=5.10.0.20240515",
 ]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.5",
+    "mkdocstrings>=0.28.1",
+    "mkdocstrings-python>=1.15.0",
+]
 
 [project.urls]
 repository = "https://github.com/specklesystems/specklepy"

src/speckle_automate/automation_context.py

@@ -19,8 +19,12 @@ from speckle_automate.schema import (
 from specklepy.api import operations
 from specklepy.api.client import SpeckleClient
 from specklepy.core.api.inputs.model_inputs import CreateModelInput
-from specklepy.core.api.inputs.version_inputs import CreateVersionInput
+from specklepy.core.api.inputs.version_inputs import (
+    CreateVersionInput,
+    MarkReceivedVersionInput,
+)
 from specklepy.core.api.models.current import Model, Version
+from specklepy.logging import metrics
 from specklepy.logging.exceptions import SpeckleException
 from specklepy.objects.base import Base
 from specklepy.transports.memory import MemoryTransport
@@ -66,6 +70,7 @@ class AutomationContext:
             if isinstance(automation_run_data, AutomationRunData)
             else AutomationRunData.model_validate_json(automation_run_data)
         )
+        metrics.set_host_app("automate")
         speckle_client = SpeckleClient(
             automation_run_data.speckle_server_url,
             automation_run_data.speckle_server_url.startswith("https"),
@@ -100,6 +105,7 @@ class AutomationContext:
         """Receive the Speckle project version that triggered this automation run."""
         # TODO: this is a quick hack to keep implementation consistency.
         # Move to proper receive many versions
+        project_id = self.automation_run_data.project_id
         version_id = self.automation_run_data.triggers[0].payload.version_id
         try:
             version = self.speckle_client.version.get(
@@ -109,7 +115,7 @@ class AutomationContext:
             raise ValueError(
                 f"""Could not receive specified version.
                 Is your environment configured correctly?
-                project_id: {self.automation_run_data.project_id}
+                project_id: {project_id}
                 model_id: {self.automation_run_data.triggers[0].payload.model_id}
                 version_id: {self.automation_run_data.triggers[0].payload.version_id}
                 """
@@ -124,6 +130,13 @@ class AutomationContext:
         base = operations.receive(
             version.referenced_object, self._server_transport, self._memory_transport
         )
+        self.speckle_client.version.received(
+            MarkReceivedVersionInput(
+                version_id=version_id,
+                project_id=project_id,
+                source_application="automate_function",
+            )
+        )
         # self._closure_tree = base["__closure"]
         print(
             f"It took {self.elapsed():.2f} seconds to receive",
@@ -245,24 +258,24 @@ class AutomationContext:
         """
         )
         if self.run_status in [AutomationStatus.SUCCEEDED, AutomationStatus.FAILED]:
-            object_results = {
-                "version": 2,
+            results_dict = self._automation_result.model_dump(by_alias=True)
+            results = {
+                "version": 3,
                 "values": {
-                    "objectResults": self._automation_result.model_dump(by_alias=True)[
-                        "objectResults"
-                    ],
+                    "objectResults": results_dict["objectResults"],
+                    "versionResult": results_dict["versionResult"],
                     "blobIds": self._automation_result.blobs,
                 },
             }
         else:
-            object_results = None
+            results = None
 
         params = {
             "projectId": self.automation_run_data.project_id,
             "functionRunId": self.automation_run_data.function_run_id,
             "status": self.run_status.value,
             "statusMessage": self._automation_result.status_message,
-            "results": object_results,
+            "results": results,
             "contextView": self._automation_result.result_view,
         }
         print(f"Reporting run status with content: {params}")
@@ -312,25 +325,49 @@ class AutomationContext:
 
         return upload_response.upload_results[0].blob_id
 
-    def mark_run_failed(self, status_message: str) -> None:
-        """Mark the current run a failure."""
-        self._mark_run(AutomationStatus.FAILED, status_message)
+    def mark_run_failed(
+        self, status_message: str, version_result: dict[str, Any] | None = None
+    ) -> None:
+        """
+        Mark the current run a failure.
+
+        Args:
+            status_message: Optional message to be displayed.
+            version_result: Optional data object,
+                that will be attached to the run results.
+                The dictionary should be JSON serializable
+        """
+        self._mark_run(AutomationStatus.FAILED, status_message, version_result)
 
     def mark_run_exception(self, status_message: str) -> None:
         """Mark the current run a failure."""
-        self._mark_run(AutomationStatus.EXCEPTION, status_message)
+        self._mark_run(AutomationStatus.EXCEPTION, status_message, None)
 
-    def mark_run_success(self, status_message: Optional[str]) -> None:
-        """Mark the current run a success with an optional message."""
-        self._mark_run(AutomationStatus.SUCCEEDED, status_message)
+    def mark_run_success(
+        self, status_message: str | None, version_result: dict[str, Any] | None = None
+    ) -> None:
+        """
+        Mark the current run a success with an optional message.
+
+        Args:
+            status_message: Optional message to be displayed.
+            version_result: Optional data object,
+                that will be attached to the run results.
+                The dictionary should be JSON serializable
+        """
+        self._mark_run(AutomationStatus.SUCCEEDED, status_message, version_result)
 
     def _mark_run(
-        self, status: AutomationStatus, status_message: Optional[str]
+        self,
+        status: AutomationStatus,
+        status_message: str | None,
+        version_result: dict[str, Any] | None,
     ) -> None:
         duration = self.elapsed()
         self._automation_result.status_message = status_message
         self._automation_result.run_status = status
         self._automation_result.elapsed = duration
+        self._automation_result.version_result = version_result
 
         msg = f"Automation run {status.value} after {duration:.2f} seconds."
         print("\n".join([msg, status_message]) if status_message else msg)

src/speckle_automate/fixtures.py

@@ -88,10 +88,8 @@ def create_test_automation_run(
 
     print(result)
 
-    return (
-        result.get("projectMutations")
-        .get("automationMutations")
-        .get("createTestAutomationRun")
+    return TestAutomationRunData.model_validate(
+        result["projectMutations"]["automationMutations"]["createTestAutomationRun"]
     )
 
 
@@ -123,9 +121,9 @@ def create_test_automation_run_data(
         project_id=test_automation_environment.project_id,
         speckle_server_url=test_automation_environment.server_url,
         automation_id=test_automation_environment.automation_id,
-        automation_run_id=test_automation_run_data["automationRunId"],
-        function_run_id=test_automation_run_data["functionRunId"],
-        triggers=test_automation_run_data["triggers"],
+        automation_run_id=test_automation_run_data.automation_run_id,
+        function_run_id=test_automation_run_data.function_run_id,
+        triggers=test_automation_run_data.triggers,
     )
 
 

src/speckle_automate/schema.py

@@ -1,7 +1,7 @@
 """"""
 
 from enum import Enum
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 from pydantic.alias_generators import to_camel
@@ -36,7 +36,7 @@ class AutomationRunData(BaseModel):
     automation_run_id: str
     function_run_id: str
 
-    triggers: List[VersionCreationTrigger]
+    triggers: list[VersionCreationTrigger]
 
     model_config = ConfigDict(
         alias_generator=to_camel, populate_by_name=True, protected_namespaces=()
@@ -49,7 +49,7 @@ class TestAutomationRunData(BaseModel):
     automation_run_id: str
     function_run_id: str
 
-    triggers: List[VersionCreationTrigger]
+    triggers: list[VersionCreationTrigger]
 
     model_config = ConfigDict(
         alias_generator=to_camel, populate_by_name=True, protected_namespaces=()
@@ -80,19 +80,20 @@ class ResultCase(AutomateBase):
 
     category: str
     level: ObjectResultLevel
-    object_app_ids: Dict[str, Optional[str]]
-    message: Optional[str]
-    metadata: Optional[Dict[str, Any]]
-    visual_overrides: Optional[Dict[str, Any]]
+    object_app_ids: dict[str, str | None]
+    message: str | None
+    metadata: dict[str, Any] | None
+    visual_overrides: dict[str, Any] | None
 
 
 class AutomationResult(AutomateBase):
     """Schema accepted by the Speckle server as a result for an automation run."""
 
     elapsed: float = 0
-    result_view: Optional[str] = None
-    result_versions: List[str] = Field(default_factory=list)
-    blobs: List[str] = Field(default_factory=list)
+    result_view: str | None = None
+    result_versions: list[str] = Field(default_factory=list)
+    blobs: list[str] = Field(default_factory=list)
     run_status: AutomationStatus = AutomationStatus.RUNNING
-    status_message: Optional[str] = None
+    status_message: str | None = None
     object_results: list[ResultCase] = Field(default_factory=list)
+    version_result: dict[str, Any] | None = None

src/speckleifc/__main__.py

@@ -18,7 +18,7 @@ def cmd_line_import() -> None:
     parser.add_argument("output_path")
     parser.add_argument("project_id")
     parser.add_argument("version_message")
-    parser.add_argument("model_id")
+    parser.add_argument("model_ingestion_id")
     # parser.add_argument("model_name")
     # parser.add_argument("region_name")
 
@@ -32,6 +32,8 @@ def cmd_line_import() -> None:
         "ifc",
     )
 
+    client: SpeckleClient | None = None
+
     try:
         client = SpeckleClient(SERVER_URL, use_ssl=not SERVER_URL.startswith("http://"))
         client.authenticate_with_token(TOKEN)
@@ -41,13 +43,14 @@ def cmd_line_import() -> None:
             args.file_path,
             project,
             args.version_message,
-            args.model_id,
+            args.model_ingestion_id,
             client,
         )
         with open(args.output_path, "w") as f:
             json.dump({"success": True, "commitId": version.id}, f)
     except Exception as e:
-        error_msg = f"IFC Importer failed with exception:\n{traceback.format_exc()}"
+        stack_trace = traceback.format_exc()
+        error_msg = f"IFC Importer failed with exception:\n{stack_trace}"
         print(error_msg)
 
         # Write error result

src/speckleifc/converter/data_object_converter.py

@@ -12,12 +12,23 @@ def data_object_to_speckle(
     step_element: entity_instance,
     children: list[Base],
     current_storey: str | None = None,
+    parent_element: entity_instance | None = None,
 ) -> DataObject:
     guid = cast(str, step_element.GlobalId)
     name = cast(str, step_element.Name or guid)
 
     properties = extract_properties(step_element)
 
+    # Add parent ID only if element's parent is also a DataObject (not a Collection)
+    # Collections are: IfcProject and IfcSpatialStructureElement types
+    if (
+        parent_element
+        and hasattr(parent_element, "GlobalId")
+        and not parent_element.is_a("IfcProject")
+        and not parent_element.is_a("IfcSpatialStructureElement")
+    ):
+        properties["parentApplicationId"] = parent_element.GlobalId
+
     # Add building storey information if available and not a building storey itself
     if current_storey and not step_element.is_a("IfcBuildingStorey"):
         properties["Building Storey"] = current_storey

src/speckleifc/converter/geometry_converter.py

@@ -4,21 +4,21 @@ from typing import cast
 
 from ifcopenshell.ifcopenshell_wrapper import (
     Triangulation,
-    TriangulationElement,
     colour,
     style,
 )
 
-from speckleifc.render_material_proxy_manager import RenderMaterialProxyManager
+from speckleifc.proxy_managers.render_material_proxy_manager import (
+    RenderMaterialProxyManager,
+)
 from specklepy.objects.base import Base
 from specklepy.objects.geometry import Mesh
 from specklepy.objects.other import RenderMaterial
 
 
 def geometry_to_speckle(
-    shape: TriangulationElement, render_material_manager: RenderMaterialProxyManager
+    geometry: Triangulation, render_material_manager: RenderMaterialProxyManager
 ) -> list[Base]:
-    geometry = cast(Triangulation, shape.geometry)
     materials = cast(Sequence[style], geometry.materials)
     MESH_COUNT = max(len(materials), 1)
 
@@ -33,7 +33,7 @@ def geometry_to_speckle(
         # Not really expected, but occasionally some meshes fail to triangulate
         return []
 
-    mapped_meshes = _pre_alloc_mesh_lists(shape, material_ids, MESH_COUNT)
+    mapped_meshes = _pre_alloc_mesh_lists(geometry, material_ids, MESH_COUNT)
     for i, mesh in enumerate(mapped_meshes):
         material = _material_to_speckle(materials[i])
         render_material_manager.add_mesh_material_mapping(material, mesh)
@@ -103,14 +103,14 @@ def _color_to_argb(colour: colour) -> int:
 
 
 def _pre_alloc_mesh_lists(
-    shape: TriangulationElement, material_ids: Sequence[int], MESH_COUNT: int
+    geometry: Triangulation, material_ids: Sequence[int], MESH_COUNT: int
 ) -> list[Mesh]:
     """
     This is a performance optimisation to pre-size the lists
     since we're expecting potential hundreds of thousands of verts in a single model
     This is very much in the hot path, so worth the extra bit of convoluted logic
     """
-    appId = cast(str, shape.guid)
+    appId = cast(str, geometry.id)
 
     material_face_counts = defaultdict(int)
     for mat_id in material_ids:

src/speckleifc/ifc_geometry_processing.py

@@ -1,6 +1,6 @@
 import multiprocessing
 
-from ifcopenshell import file, ifcopenshell_wrapper, open, sqlite
+from ifcopenshell import SchemaError, file, ifcopenshell_wrapper, open, sqlite
 from ifcopenshell.geom import iterator, settings
 
 from specklepy.logging.exceptions import SpeckleException
@@ -12,8 +12,10 @@ def _create_iterator_settings() -> settings:
     ifc_settings.set("triangulation-type", ifcopenshell_wrapper.TRIANGLE_MESH)
     # no need to weld verts
     ifc_settings.set("weld-vertices", False)
-    # Speckle meshes are all in world coords
-    ifc_settings.set("use-world-coords", True)
+    #
+    ifc_settings.set("use-world-coords", False)
+    ifc_settings.set("permissive-shape-reuse", True)
+
     # Tiny performance improvement,
     ifc_settings.set("no-wire-intersection-check", True)
     # Rendermaterials inherit the material names instead of type + unique id
@@ -33,7 +35,14 @@ def _create_iterator_settings() -> settings:
 
 
 def open_ifc(file_path: str) -> file:
-    ifc_file = open(file_path)
+    try:
+        ifc_file = open(file_path)
+    except SchemaError:
+        raise
+    except FileNotFoundError:
+        raise
+    except Exception as ex:
+        raise SpeckleException("File could not be opened as an IFC file") from ex
 
     if isinstance(ifc_file, file):
         return ifc_file
@@ -42,4 +51,10 @@ def open_ifc(file_path: str) -> file:
 
 
 def create_geometry_iterator(ifc_file: file | sqlite) -> iterator:
-    return iterator(_create_iterator_settings(), ifc_file, multiprocessing.cpu_count())
+    GEOMETRY_LIBRARY = "hybrid-opencascade-cgal"  # First OCC then fallback to CGAL
+    return iterator(
+        _create_iterator_settings(),
+        ifc_file,
+        multiprocessing.cpu_count(),
+        geometry_library=GEOMETRY_LIBRARY,  # type: ignore
+    )

src/speckleifc/importer.py

@@ -1,10 +1,10 @@
 import time
 from dataclasses import dataclass, field
-from typing import cast
+from typing import List, cast
 
 from ifcopenshell.entity_instance import entity_instance
 from ifcopenshell.geom import file
-from ifcopenshell.ifcopenshell_wrapper import TriangulationElement
+from ifcopenshell.ifcopenshell_wrapper import Triangulation, TriangulationElement
 
 from speckleifc.converter.data_object_converter import data_object_to_speckle
 from speckleifc.converter.geometry_converter import geometry_to_speckle
@@ -12,41 +12,71 @@ from speckleifc.converter.project_converter import project_to_speckle
 from speckleifc.converter.spatial_element_converter import spatial_element_to_speckle
 from speckleifc.ifc_geometry_processing import create_geometry_iterator
 from speckleifc.ifc_openshell_helpers import get_children
-from speckleifc.level_proxy_manager import LevelProxyManager
-from speckleifc.render_material_proxy_manager import RenderMaterialProxyManager
+from speckleifc.proxy_managers.instance_proxy_manager import InstanceProxyManager
+from speckleifc.proxy_managers.level_proxy_manager import LevelProxyManager
+from speckleifc.proxy_managers.render_material_proxy_manager import (
+    RenderMaterialProxyManager,
+)
 from specklepy.logging.exceptions import SpeckleException
 from specklepy.objects import Base
 from specklepy.objects.data_objects import DataObject
+from specklepy.objects.models.collections.collection import Collection
+from specklepy.objects.proxies import InstanceProxy
 
 
 @dataclass
 class ImportJob:
     ifc_file: file
-    cached_display_values: dict[int, list[Base]] = field(default_factory=dict)  # noqa: F821
+
     _render_material_manager: RenderMaterialProxyManager = field(
         default_factory=lambda: RenderMaterialProxyManager()
     )
     _level_proxy_manager: LevelProxyManager = field(
         default_factory=lambda: LevelProxyManager()
     )
+    _instance_proxy_manager: InstanceProxyManager = field(
+        default_factory=lambda: InstanceProxyManager()
+    )
     geometries_count: int = 0
     geometries_used: int = 0
     _current_storey_data_object: DataObject | None = field(default=None, init=False)
 
-    def convert_element(self, step_element: entity_instance) -> Base:
+    _display_value_cache: dict[int, list[Base]] = field(default_factory=dict)
+    """Maps an instance step ID to a list of instances"""
+
+    def convert_element(
+        self,
+        step_element: entity_instance,
+        parent_element: entity_instance | None = None,
+    ) -> Base:
+        try:
+            return self._convert_element(step_element, parent_element)
+        except SpeckleException:
+            raise
+        except Exception as ex:
+            raise SpeckleException(
+                f"Failed to convert {step_element.is_a()} #{step_element.id()}"
+            ) from ex
+
+    def _convert_element(
+        self,
+        step_element: entity_instance,
+        parent_element: entity_instance | None = None,
+    ) -> Base:
         # Track current storey context and store for level proxies
         previous_storey_data_object = self._current_storey_data_object
         if step_element.is_a("IfcBuildingStorey"):
             # Convert the building storey to a DataObject for the level proxy
-            storey_display_value = self.cached_display_values.get(step_element.id(), [])
+            storey_display_value = self._display_value_cache.get(step_element.id(), [])
             self._current_storey_data_object = data_object_to_speckle(
-                storey_display_value, step_element, []
+                storey_display_value, step_element, [], parent_element=None
             )
 
         children = self._convert_children(step_element)
-        display_value = self.cached_display_values.get(step_element.id(), [])
+        id = step_element.id()
+        display_value = self._display_value_cache.get(id, [])
 
-        if display_value is not None:
+        if display_value:
             self.geometries_used += 1
 
         # Extract current storey name from DataObject if available
@@ -64,7 +94,11 @@ class ImportJob:
             )
         else:
             result = data_object_to_speckle(
-                display_value, step_element, children, current_storey_name
+                display_value,
+                step_element,
+                children,
+                current_storey_name,
+                parent_element,
             )
             # Associate non-spatial elements with current storey for level proxies
             if self._current_storey_data_object is not None and result.applicationId:
@@ -78,7 +112,7 @@ class ImportJob:
 
     def _convert_children(self, step_element: entity_instance) -> list[Base]:
         return [
-            self.convert_element(i)
+            self.convert_element(i, parent_element=step_element)
             for i in get_children(step_element)
             if self._should_convert(i)
         ]
@@ -110,21 +144,53 @@ class ImportJob:
     def pre_process_geometry(self) -> None:
         iterator = create_geometry_iterator(self.ifc_file)
         if not iterator.initialize():
-            raise SpeckleException(
-                "geometry iterator failed to initialize for the given file"
-            )
+            raise SpeckleException("Failed to find any geometry in file")
         self.geometries_count = 0
         while True:
             shape = cast(TriangulationElement, iterator.get())
             self.geometries_count += 1
             id = cast(int, shape.id)
-
-            display_value = geometry_to_speckle(shape, self._render_material_manager)
-            self.cached_display_values[id] = display_value
-
+            try:
+                display_value = self._create_display_value(shape)
+                self._display_value_cache[id] = display_value
+            except Exception as ex:
+                raise SpeckleException(
+                    f"Failed to convert geometry with id: {id}"
+                ) from ex
             if not iterator.next():
                 break
 
+    def _create_display_value(self, shape: TriangulationElement) -> List[Base]:
+        geometry = cast(Triangulation, shape.geometry)
+        display_value_geometry = geometry_to_speckle(
+            geometry, self._render_material_manager
+        )
+
+        definition_ids = self._instance_proxy_manager.add_display_value_definitions(
+            display_value_geometry
+        )
+        matrix = shape.transformation.matrix
+        transposed = [
+            matrix[0], matrix[4], matrix[8], matrix[12],
+            matrix[1], matrix[5], matrix[9], matrix[13],
+            matrix[2], matrix[6], matrix[10], matrix[14],
+            matrix[3], matrix[7], matrix[11], matrix[15],
+        ]  # fmt: skip
+
+        return [
+            cast(
+                Base,
+                InstanceProxy(
+                    units="m",
+                    definitionId=definition_id,
+                    transform=transposed,
+                    maxDepth=0,
+                    applicationId=f"{shape.guid}:{definition_id}",
+                ),
+            )
+            for definition_id in definition_ids
+        ]
+
     def _convert_project_tree(self) -> Base:
         projects = self.ifc_file.by_type("IfcProject", False)
         if len(projects) != 1:
@@ -132,10 +198,22 @@ class ImportJob:
         project = projects[0]
 
         tree = self.convert_element(project)
+        if not isinstance(tree, Collection):
+            raise TypeError("Expected root object to convert to a Collection")
+
         tree["renderMaterialProxies"] = list(
             self._render_material_manager.render_material_proxies.values()
         )
         tree["levelProxies"] = list(self._level_proxy_manager.level_proxies.values())
+        tree["instanceDefinitionProxies"] = list(
+            self._instance_proxy_manager.instance_definition_proxies.values()
+        )
+        tree.elements.append(
+            Collection(
+                name="definitionGeometry",
+                elements=list(self._instance_proxy_manager.instance_geometry.values()),
+            )
+        )
         tree["version"] = 3
 
         return tree

src/speckleifc/main.py

@@ -1,9 +1,19 @@
+import contextlib
+import importlib.metadata
 import time
+import traceback
+from pathlib import Path
 
 from speckleifc.ifc_geometry_processing import open_ifc
 from speckleifc.importer import ImportJob
 from specklepy.core.api.client import SpeckleClient
-from specklepy.core.api.inputs.version_inputs import CreateVersionInput
+from specklepy.core.api.inputs.model_ingestion_inputs import (
+    ModelIngestionFailedInput,
+    ModelIngestionStartProcessingInput,
+    ModelIngestionSuccessInput,
+    ModelIngestionUpdateInput,
+    SourceDataInput,
+)
 from specklepy.core.api.models.current import Project, Version
 from specklepy.core.api.operations import send
 from specklepy.logging import metrics
@@ -13,48 +23,106 @@ from specklepy.transports.server import ServerTransport
 def open_and_convert_file(
     file_path: str,
     project: Project,
-    version_message: str | None,
-    model_id: str,
+    version_message: str,
+    model_ingestion_id: str,
     client: SpeckleClient,
 ) -> Version:
-    start = time.time()
-    very_start = start
+    try:
+        start = time.time()
+        very_start = start
+        path = Path(file_path)
 
-    account = client.account
-    server_url = account.serverInfo.url
-    assert server_url
-    remote_transport = ServerTransport(project.id, account=account)
+        specklepy_version = importlib.metadata.version("specklepy")
+        client.model_ingestion.start_processing(
+            ModelIngestionStartProcessingInput(
+                project_id=project.id,
+                ingestion_id=model_ingestion_id,
+                progress_message="Importing IFC file",
+                source_data=SourceDataInput(
+                    file_name=path.name,
+                    file_size_bytes=path.stat().st_size,
+                    source_application_slug=metrics.HOST_APP,
+                    source_application_version=specklepy_version,
+                ),
+            )
+        )
 
-    ifc_file = open_ifc(file_path)  # pyright: ignore[reportUnknownVariableType]
-    import_job = ImportJob(ifc_file)  # pyright: ignore[reportUnknownArgumentType]
-    data = import_job.convert()
+        account = client.account
+        server_url = account.serverInfo.url
+        assert server_url
+        remote_transport = ServerTransport(project.id, account=account)
 
-    print(f"File conversion complete after {(time.time() - start) * 1000}ms")
+        ifc_file = open_ifc(file_path)  # pyright: ignore[reportUnknownVariableType]
 
-    start = time.time()
+        client.model_ingestion.update_progress(
+            ModelIngestionUpdateInput(
+                project_id=project.id,
+                ingestion_id=model_ingestion_id,
+                progress_message="Converting file",
+                progress=None,
+            )
+        )
+        import_job = ImportJob(ifc_file)  # pyright: ignore[reportUnknownArgumentType]
+        data = import_job.convert()
 
-    root_id = send(data, transports=[remote_transport], use_default_cache=False)
-    print(f"Sending to speckle complete after: {(time.time() - start) * 1000}ms")
+        print(f"File conversion complete after {(time.time() - start) * 1000}ms")
 
-    start = time.time()
+        start = time.time()
 
-    create_version = CreateVersionInput(
-        object_id=root_id,
-        model_id=model_id,
-        project_id=project.id,
-        message=version_message,
-        source_application="ifc",
-    )
-    version = client.version.create(create_version)
-    end = time.time()
-    print(f"Version committed after: {(end - start) * 1000}ms")
+        client.model_ingestion.update_progress(
+            ModelIngestionUpdateInput(
+                project_id=project.id,
+                ingestion_id=model_ingestion_id,
+                progress_message="Uploading objects",
+                progress=None,
+            )
+        )
+        root_id = send(data, transports=[remote_transport], use_default_cache=False)
+        print(f"Sending to speckle complete after: {(time.time() - start) * 1000}ms")
 
-    print(f"Total time (to commit): {(end - very_start) * 1000}ms")
-    del ifc_file
+        start = time.time()
 
-    custom_properties = {"ui": "dui3", "actionSource": "import"}
-    if project.workspace_id:
-        custom_properties["workspace_id"] = project.workspace_id
-    metrics.track(metrics.SEND, account, custom_properties)
+        version_id = client.model_ingestion.complete(
+            ModelIngestionSuccessInput(
+                project_id=project.id,
+                ingestion_id=model_ingestion_id,
+                root_object_id=root_id,
+                version_message=version_message,
+            )
+        )
 
-    return version
+        # needed to query version until ingestion api expands to serve it
+        version = client.version.get(version_id, project.id)
+
+        end = time.time()
+        print(f"Version committed after: {(end - start) * 1000}ms")
+
+        print(f"Total time (to commit): {(end - very_start) * 1000}ms")
+        del ifc_file
+
+        custom_properties = {"ui": "dui3", "actionSource": "import"}
+        if project.workspace_id:
+            custom_properties["workspace_id"] = project.workspace_id
+
+        metrics.track(
+            metrics.SEND,
+            account,
+            custom_properties,
+            send_sync=True,
+            track_email=True,
+        )
+
+        return version
+    except Exception as e:
+        stack_trace = traceback.format_exc()
+        with contextlib.suppress(Exception):
+            # make sure to not report process kills when we're cancelling
+            client.model_ingestion.fail_with_error(
+                ModelIngestionFailedInput(
+                    project_id=project.id,
+                    ingestion_id=model_ingestion_id,
+                    error_reason=str(e),
+                    error_stacktrace=stack_trace,
+                )
+            )
+        raise e

src/speckleifc/property_extraction.py

@@ -1,3 +1,4 @@
+import math
 from typing import Any, Tuple
 
 from ifcopenshell.entity_instance import entity_instance
@@ -134,6 +135,10 @@ def _get_quantities(
             value = getattr(quantity, quantity.attribute_name(3))
             unit_info = _get_unit_info(element, quantity)
 
+            # Server does not consider `NaN` valid json
+            if math.isnan(value):
+                value = None
+
             if unit_info:
                 # Create structured quantity object with units
                 results[quantity_name] = {

src/speckleifc/proxy_managers/instance_proxy_manager.py

@@ -0,0 +1,43 @@
+from typing import Sequence
+
+from specklepy.objects.base import Base
+from specklepy.objects.proxies import InstanceDefinitionProxy
+
+
+class InstanceProxyManager:
+    def __init__(self):
+        self._instance_definition_proxies: dict[str, InstanceDefinitionProxy] = {}
+        """definition proxies to be added directly to the root"""
+        self._instance_geometry: dict[str, Base] = {}
+        """The geometry that will be added in it's own collection under the root"""
+
+    @property
+    def instance_definition_proxies(self) -> dict[str, InstanceDefinitionProxy]:
+        return self._instance_definition_proxies
+
+    @property
+    def instance_geometry(self) -> dict[str, Base]:
+        return self._instance_geometry
+
+    def add_display_value_definitions(self, geometry: Sequence[Base]) -> list[str]:
+        result: list[str] = []
+        for m in geometry:
+            if not m.applicationId:
+                raise ValueError("geometry with no applicationId cannot be proxied ")
+            definition_id = f"DEFINITION:{m.applicationId}"
+            result.append(definition_id)
+            self._add_definition(definition_id, [m.applicationId], 0)
+            self._instance_geometry[m.applicationId] = m
+
+        return result
+
+    def _add_definition(
+        self, definition_id: str, objects: list[str], max_depth: int
+    ) -> None:
+        proxy = InstanceDefinitionProxy(
+            applicationId=definition_id,
+            name=definition_id,
+            objects=objects,
+            maxDepth=max_depth,
+        )
+        self._instance_definition_proxies[definition_id] = proxy

src/specklepy/api/client.py

@@ -4,6 +4,7 @@ from specklepy.api.credentials import Account
 from specklepy.api.resources import (
     ActiveUserResource,
     FileImportResource,
+    ModelIngestionResource,
     ModelResource,
     OtherUserResource,
     ProjectInviteResource,
@@ -119,6 +120,12 @@ class SpeckleClient(CoreSpeckleClient):
             client=self.httpclient,
             server_version=server_version,
         )
+        self.model_ingestion = ModelIngestionResource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
         self.file_import = FileImportResource(
             account=self.account,
             basepath=self.url,

src/specklepy/api/resources/__init__.py

@@ -1,5 +1,8 @@
 from specklepy.api.resources.current.active_user_resource import ActiveUserResource
 from specklepy.api.resources.current.file_import_resource import FileImportResource
+from specklepy.api.resources.current.model_ingestion_resource import (
+    ModelIngestionResource,
+)
 from specklepy.api.resources.current.model_resource import ModelResource
 from specklepy.api.resources.current.other_user_resource import OtherUserResource
 from specklepy.api.resources.current.project_invite_resource import (
@@ -22,4 +25,6 @@ __all__ = [
     "SubscriptionResource",
     "VersionResource",
     "WorkspaceResource",
+    "FileImportResource",
+    "ModelIngestionResource",
 ]

src/specklepy/api/resources/current/file_import_resource.py

@@ -15,7 +15,7 @@ from specklepy.logging import metrics
 
 
 class FileImportResource(CoreResource):
-    """API Access class for projects"""
+    """API Access class for file imports"""
 
     def __init__(self, account, basepath, client, server_version) -> None:
         super().__init__(

src/specklepy/api/resources/current/model_ingestion_resource.py

@@ -0,0 +1,57 @@
+from specklepy.core.api.inputs.model_ingestion_inputs import (
+    ModelIngestionCancelledInput,
+    ModelIngestionCreateInput,
+    ModelIngestionFailedInput,
+    ModelIngestionRequeueInput,
+    ModelIngestionStartProcessingInput,
+    ModelIngestionSuccessInput,
+    ModelIngestionUpdateInput,
+)
+from specklepy.core.api.models.current import (
+    ModelIngestion,
+)
+from specklepy.core.api.resources import (
+    ModelIngestionResource as CoreResource,
+)
+from specklepy.logging import metrics
+
+
+class ModelIngestionResource(CoreResource):
+    """API Access class for model ingestion"""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(account, basepath, client, server_version)
+
+    def create(self, input: ModelIngestionCreateInput) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Create"})
+        return super().create(input)
+
+    def get_ingestion(self, project_id: str, model_ingestion_id: str) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Get"})
+        return super().get_ingestion(project_id, model_ingestion_id)
+
+    def update_progress(self, input: ModelIngestionUpdateInput) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Update"})
+        return super().update_progress(input)
+
+    def start_processing(
+        self, input: ModelIngestionStartProcessingInput
+    ) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Start Processing"})
+        return super().start_processing(input)
+
+    def requeue(self, input: ModelIngestionRequeueInput) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Update"})
+        return super().requeue(input)
+
+    def complete(self, input: ModelIngestionSuccessInput) -> str:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion End"})
+        return super().complete(input)
+
+    def fail_with_error(self, input: ModelIngestionFailedInput) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Error"})
+        return super().fail_with_error(input)
+
+    def fail_with_cancel(self, input: ModelIngestionCancelledInput) -> ModelIngestion:
+        metrics.track(metrics.SDK, self.account, {"name": "Ingestion Cancel"})
+        return super().fail_with_cancel(input)

src/specklepy/api/resources/current/model_resource.py

@@ -8,6 +8,10 @@ from specklepy.core.api.inputs.model_inputs import (
 )
 from specklepy.core.api.inputs.project_inputs import ProjectModelsFilter
 from specklepy.core.api.models import Model, ModelWithVersions, ResourceCollection
+from specklepy.core.api.models.current import (
+    ModelPermissionChecks,
+    PermissionCheckResult,
+)
 from specklepy.core.api.resources import ModelResource as CoreResource
 from specklepy.logging import metrics
 
@@ -72,3 +76,17 @@ class ModelResource(CoreResource):
     def update(self, input: UpdateModelInput) -> Model:
         metrics.track(metrics.SDK, self.account, {"name": "Model Update"})
         return super().update(input)
+
+    def get_permissions(self, model_id: str, project_id: str) -> ModelPermissionChecks:
+        metrics.track(metrics.SDK, self.account, {"name": "Model Get Permissions"})
+        return super().get_permissions(model_id, project_id)
+
+    def can_create_model_ingestion(
+        self, model_id: str, project_id: str
+    ) -> PermissionCheckResult:
+        metrics.track(
+            metrics.SDK,
+            self.account,
+            {"name": "Model Get Permissions canCreateIngestion"},
+        )
+        return super().can_create_model_ingestion(model_id, project_id)

src/specklepy/core/api/client.py

@@ -12,6 +12,7 @@ from specklepy.core.api.credentials import Account
 from specklepy.core.api.resources import (
     ActiveUserResource,
     FileImportResource,
+    ModelIngestionResource,
     ModelResource,
     OtherUserResource,
     ProjectInviteResource,
@@ -131,6 +132,19 @@ class SpeckleClient:
         self.account = Account.from_token(token, self.url)
         self._set_up_client()
 
+        userData = self.active_user.get()
+
+        # None if the token lacked the profile:read scope or if it was None
+        if userData:
+            self.account.userInfo.id = userData.id
+            self.account.userInfo.email = userData.email
+            self.account.userInfo.name = userData.name
+            self.account.userInfo.company = userData.company
+            self.account.userInfo.avatar = userData.avatar
+
+        self.account.serverInfo = self.server.get()
+        self.account.serverInfo.url = self.url
+
     def authenticate_with_account(self, account: Account) -> None:
         """Authenticate the client using an Account object
         The account is saved in the client object and a synchronous GraphQL
@@ -143,6 +157,21 @@ class SpeckleClient:
         self.account = account
         self._set_up_client()
 
+        try:
+            _ = self.active_user.get()
+        except SpeckleException as ex:
+            if isinstance(ex.exception, TransportServerError):
+                if ex.exception.code == 403:
+                    warn(
+                        SpeckleWarning(
+                            "Possibly invalid token - could not authenticate "
+                            f"Speckle Client for server {self.url}"
+                        ),
+                        stacklevel=2,
+                    )
+                else:
+                    raise ex
+
     def _set_up_client(self) -> None:
         headers = {
             "Authorization": f"Bearer {self.account.token}",
@@ -162,21 +191,6 @@ class SpeckleClient:
 
         self._init_resources()
 
-        try:
-            _ = self.active_user.get()
-        except SpeckleException as ex:
-            if isinstance(ex.exception, TransportServerError):
-                if ex.exception.code == 403:
-                    warn(
-                        SpeckleWarning(
-                            "Possibly invalid token - could not authenticate "
-                            f"Speckle Client for server {self.url}"
-                        ),
-                        stacklevel=2,
-                    )
-                else:
-                    raise ex
-
     def execute_query(self, query: str) -> Dict:
         return self.httpclient.execute(query)
 
@@ -237,6 +251,12 @@ class SpeckleClient:
             client=self.httpclient,
             server_version=server_version,
         )
+        self.model_ingestion = ModelIngestionResource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
         self.subscription = SubscriptionResource(
             account=self.account,
             basepath=self.ws_url,

src/specklepy/core/api/credentials.py

@@ -37,7 +37,7 @@ class Account(BaseModel):
         return self.__repr__()
 
     @classmethod
-    def from_token(cls, token: str, server_url: str = None):
+    def from_token(cls, token: str, server_url: str | None = None):
         acct = cls(token=token)
         acct.serverInfo.url = server_url
         return acct

src/specklepy/core/api/enums.py

@@ -7,6 +7,7 @@ class ProjectVisibility(str, Enum):
     PRIVATE = "PRIVATE"
     PUBLIC = "PUBLIC"
     UNLISTED = "UNLISTED"
+    """Deprecated, use PUBLIC instead"""
     WORKSPACE = "WORKSPACE"
 
 
@@ -30,3 +31,18 @@ class ProjectVersionsUpdatedMessageType(str, Enum):
     CREATED = "CREATED"
     DELETED = "DELETED"
     UPDATED = "UPDATED"
+
+
+class ProjectModelIngestionUpdatedMessageType(str, Enum):
+    CANCELLATION_REQUESTED = "cancellationRequested"
+    CREATED = "created"
+    DELETED = "deleted"
+    UPDATED = "updated"
+
+
+class ModelIngestionStatus(str, Enum):
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+    PROCESSING = "processing"
+    QUEUED = "queued"
+    SUCCESS = "success"

src/specklepy/core/api/inputs/model_ingestion_inputs.py

@@ -0,0 +1,77 @@
+from specklepy.core.api.enums import ProjectModelIngestionUpdatedMessageType
+from specklepy.core.api.models.graphql_base_model import GraphQLBaseModel
+
+
+class SourceDataInput(GraphQLBaseModel):
+    source_application_slug: str
+    source_application_version: str
+    file_name: str | None
+    file_size_bytes: int | None
+
+
+class ModelIngestionCreateInput(GraphQLBaseModel):
+    model_id: str
+    project_id: str
+    progress_message: str
+    source_data: SourceDataInput
+
+
+class ModelIngestionStartProcessingInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    progress_message: str
+    source_data: SourceDataInput
+
+
+class ModelIngestionRequeueInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    progress_message: str
+
+
+class ModelIngestionUpdateInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    progress: float | None
+    progress_message: str
+
+
+class ModelIngestionSuccessInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    root_object_id: str
+    version_message: str | None
+
+
+class ModelIngestionFailedInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    error_reason: str
+    error_stacktrace: str | None
+
+
+class ModelIngestionCancelledInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    cancellation_message: str
+
+
+class ModelIngestionRequestCancellationInput(GraphQLBaseModel):
+    ingestion_id: str
+    project_id: str
+    cancellation_message: str
+
+
+class ModelIngestionReference(GraphQLBaseModel):
+    """
+    `@oneOf` i.e. server expects **either** `ingestion_id` or `model_id`, but not both.
+    """
+
+    ingestion_id: str | None
+    model_id: str | None
+
+
+class ProjectModelIngestionSubscriptionInput(GraphQLBaseModel):
+    project_id: str
+    ingestion_reference: ModelIngestionReference
+    message_type: ProjectModelIngestionUpdatedMessageType | None = None

src/specklepy/core/api/inputs/version_inputs.py

@@ -34,4 +34,8 @@ class MarkReceivedVersionInput(GraphQLBaseModel):
     version_id: str
     project_id: str
     source_application: str
+    """
+    IMPORTANT: this is meant to be the slug of the application that has done the
+    receiving, not to be confused with `Version.sourceApplication`
+    """
     message: Optional[str] = None

src/specklepy/core/api/models/current.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Generic, List, TypeVar
 
-from specklepy.core.api.enums import ProjectVisibility
+from specklepy.core.api.enums import ModelIngestionStatus, ProjectVisibility
 from specklepy.core.api.models.graphql_base_model import GraphQLBaseModel
 from specklepy.logging.exceptions import WorkspacePermissionException
 
@@ -105,7 +105,7 @@ class PendingStreamCollaborator(GraphQLBaseModel):
     project_name: str
     title: str
     role: str
-    invited_by: LimitedUser
+    invited_by: LimitedUser | None = None
     user: LimitedUser | None = None
     token: str | None
 
@@ -137,6 +137,12 @@ class Version(GraphQLBaseModel):
     source_application: str | None
 
 
+class ModelPermissionChecks(GraphQLBaseModel):
+    can_update: "PermissionCheckResult"
+    can_delete: "PermissionCheckResult"
+    can_create_version: "PermissionCheckResult"
+
+
 class Model(GraphQLBaseModel):
     author: LimitedUser | None
     created_at: datetime
@@ -156,7 +162,6 @@ class ProjectPermissionChecks(GraphQLBaseModel):
     can_create_model: "PermissionCheckResult"
     can_delete: "PermissionCheckResult"
     can_load: "PermissionCheckResult"
-    can_publish: "PermissionCheckResult"
 
 
 class Project(GraphQLBaseModel):
@@ -244,3 +249,17 @@ class FileImport(GraphQLBaseModel):
 class FileUploadUrl(GraphQLBaseModel):
     url: str
     file_id: str
+
+
+class ModelIngestionStatusData(GraphQLBaseModel):
+    status: ModelIngestionStatus
+    progress_message: str | None = None
+
+
+class ModelIngestion(GraphQLBaseModel):
+    id: str
+    created_at: datetime
+    updated_at: datetime
+    cancellation_requested: bool
+    model_id: str
+    status_data: ModelIngestionStatusData

src/specklepy/core/api/models/subscription_messages.py

@@ -1,12 +1,13 @@
 from typing import Optional
 
 from specklepy.core.api.enums import (
+    ProjectModelIngestionUpdatedMessageType,
     ProjectModelsUpdatedMessageType,
     ProjectUpdatedMessageType,
     ProjectVersionsUpdatedMessageType,
     UserProjectsUpdatedMessageType,
 )
-from specklepy.core.api.models.current import Model, Project, Version
+from specklepy.core.api.models.current import Model, ModelIngestion, Project, Version
 from specklepy.core.api.models.graphql_base_model import GraphQLBaseModel
 
 
@@ -33,3 +34,8 @@ class ProjectVersionsUpdatedMessage(GraphQLBaseModel):
     type: ProjectVersionsUpdatedMessageType
     model_id: str
     version: Optional[Version]
+
+
+class ProjectModelIngestionUpdatedMessage(GraphQLBaseModel):
+    model_ingestion: ModelIngestion
+    type: ProjectModelIngestionUpdatedMessageType

src/specklepy/core/api/resources/__init__.py

@@ -1,5 +1,8 @@
 from specklepy.core.api.resources.current.active_user_resource import ActiveUserResource
 from specklepy.core.api.resources.current.file_import_resource import FileImportResource
+from specklepy.core.api.resources.current.model_ingestion_resource import (
+    ModelIngestionResource,
+)
 from specklepy.core.api.resources.current.model_resource import ModelResource
 from specklepy.core.api.resources.current.other_user_resource import OtherUserResource
 from specklepy.core.api.resources.current.project_invite_resource import (
@@ -24,4 +27,6 @@ __all__ = [
     "SubscriptionResource",
     "VersionResource",
     "WorkspaceResource",
+    "FileImportResource",
+    "ModelIngestionResource",
 ]

src/specklepy/core/api/resources/current/file_import_resource.py

@@ -16,13 +16,15 @@ from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse
 from specklepy.logging.exceptions import SpeckleException
 
+NAME = "file_import"
+
 
 class UploadFileResponse(GraphQLBaseModel):
     etag: str
 
 
 class FileImportResource(ResourceBase):
-    """API Access class for project invites"""
+    """API Access class for file imports"""
 
     def __init__(
         self,
@@ -36,7 +38,7 @@ class FileImportResource(ResourceBase):
             basepath=basepath,
             client=client,
             server_version=server_version,
-            name="file-import",
+            name=NAME,
         )
 
     def finish_file_import_job(self, input: FinishFileImportInput) -> bool:

src/specklepy/core/api/resources/current/model_ingestion_resource.py

@@ -0,0 +1,397 @@
+from typing import Any, Tuple
+
+from gql import Client, gql
+
+from specklepy.api.credentials import Account
+from specklepy.core.api.inputs.model_ingestion_inputs import (
+    ModelIngestionCancelledInput,
+    ModelIngestionCreateInput,
+    ModelIngestionFailedInput,
+    ModelIngestionRequestCancellationInput,
+    ModelIngestionRequeueInput,
+    ModelIngestionStartProcessingInput,
+    ModelIngestionSuccessInput,
+    ModelIngestionUpdateInput,
+)
+from specklepy.core.api.models.current import (
+    ModelIngestion,
+)
+from specklepy.core.api.resource import ResourceBase
+from specklepy.core.api.responses import DataResponse
+
+NAME = "ingestion"
+
+
+class ModelIngestionResource(ResourceBase):
+    """API Access class for model ingestion"""
+
+    def __init__(
+        self,
+        account: Account,
+        basepath: str,
+        client: Client,
+        server_version: Tuple[Any, ...] | None,
+    ) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            server_version=server_version,
+        )
+
+    def get_ingestion(self, project_id: str, model_ingestion_id: str) -> ModelIngestion:
+        QUERY = gql(
+            """
+            query Query($projectId: String!, $modelIngestionId: ID!) {
+              data:project(id: $projectId) {
+                data:ingestion(id: $modelIngestionId) {
+                  id
+                  createdAt
+                  updatedAt
+                  modelId
+                  cancellationRequested
+                  statusData {
+                    ... on HasModelIngestionStatus {
+                      status
+                    }
+                    ... on HasProgressMessage {
+                      progressMessage
+                    }
+                  }
+                }
+              }
+            }
+            """  # noqa: E501
+        )
+
+        variables = {
+            "projectId": project_id,
+            "modelIngestionId": model_ingestion_id,
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[ModelIngestion]],
+            QUERY,
+            variables,
+        ).data.data
+
+    def create(self, input: ModelIngestionCreateInput) -> ModelIngestion:
+        QUERY = gql(
+            """
+            mutation IngestionCreate($input: ModelIngestionCreateInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: create(input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+           """
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]], QUERY, variables
+        ).data.data.data
+
+    def start_processing(
+        self, input: ModelIngestionStartProcessingInput
+    ) -> ModelIngestion:
+        QUERY = gql(
+            """
+            mutation IngestionStartProcessing($input: ModelIngestionStartProcessingInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: startProcessing(input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+           """  # noqa: E501
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]], QUERY, variables
+        ).data.data.data
+
+    def requeue(self, input: ModelIngestionRequeueInput) -> ModelIngestion:
+        QUERY = gql(
+            """
+            mutation IngestionRequeue($input: ModelIngestionRequeueInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: requeue(input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+           """  # noqa: E501
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]], QUERY, variables
+        ).data.data.data
+
+    def update_progress(self, input: ModelIngestionUpdateInput) -> ModelIngestion:
+        QUERY = gql(
+            """
+            mutation IngestionUpdateProgress(
+              $input: ModelIngestionUpdateInput!
+            ) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: updateProgress(input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+           """
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]], QUERY, variables
+        ).data.data.data
+
+    def complete(self, input: ModelIngestionSuccessInput) -> str:
+        """
+        Request that the server completes the ingestion by creating a version
+        If successful, the job will be in a terminal "successful" state.
+
+        For failed Ingestions, use `fail_with_error` instead
+        For user cancellation, use `fail_with_cancelled` instead
+
+        Arguments:
+            input {ModelIngestionSuccessInput} -- input variable
+
+        Returns:
+            str -- the id of the version that was just created to complete the ingestion
+        """
+        QUERY = gql(
+            """
+            mutation IngestionComplete($input: ModelIngestionSuccessInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: completeWithVersion(input: $input) {
+                    data:statusData {
+                      ... on ModelIngestionSuccessStatus {
+                        data:versionId
+                      }
+                    }
+                  }
+                }
+              }
+            }
+           """
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[DataResponse[DataResponse[str]]]]],
+            QUERY,
+            variables,
+        ).data.data.data.data.data
+
+    def fail_with_error(self, input: ModelIngestionFailedInput) -> ModelIngestion:
+        """
+        Fail the job with an error.
+        For user requested cancellation, use `fail_with_cancelled` instead
+        """
+        QUERY = gql(
+            """
+            mutation IngestionFailWithError($input: ModelIngestionFailedInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: failWithError(input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            """
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]],
+            QUERY,
+            variables,
+        ).data.data.data
+
+    def fail_with_cancel(self, input: ModelIngestionCancelledInput) -> ModelIngestion:
+        """
+        Fail the ingestion with a `cancelled` status.
+        This should only be done if the user has explicitly requested cancellation
+        Other forms of cancellation use `fail_with_error`
+        The ingestion should then enter a terminal "canceled" state
+        """
+        QUERY = gql(
+            """
+            mutation IngestionFailWithCancel($input: ModelIngestionCancelledInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: failWithCancel(input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            """
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]],
+            QUERY,
+            variables,
+        ).data.data.data
+
+    def request_cancellation(
+        self, input: ModelIngestionRequestCancellationInput
+    ) -> ModelIngestion:
+        """
+        Request that the ingestion is canceled.
+
+        Note: simply calling this mutation does not immediately cancel,
+        it doesn't even guarantee it will be canceled at all.
+        It's up to the client to observe this cancellation request
+        via `subscription.project_model_ingestion_cancellation_requested`
+        and report it as cancelled (via `ingestion.fail_with_cancel`
+
+        See "cooperative cancellation pattern"
+        """
+        QUERY = gql(
+            """
+            mutation IngestionRequestCancellation($input: ModelIngestionRequestCancellationInput!) {
+              data: projectMutations {
+                data: modelIngestionMutations {
+                  data: requestCancellation (input: $input) {
+                    id
+                    createdAt
+                    updatedAt
+                    modelId
+                    cancellationRequested
+                    statusData {
+                      ... on HasModelIngestionStatus {
+                        status
+                      }
+                      ... on HasProgressMessage {
+                        progressMessage
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            """  # noqa: E501
+        )
+
+        variables = {
+            "input": input.model_dump(warnings="error", by_alias=True),
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelIngestion]]],
+            QUERY,
+            variables,
+        ).data.data.data

src/specklepy/core/api/resources/current/model_resource.py

@@ -10,6 +10,10 @@ from specklepy.core.api.inputs.model_inputs import (
 )
 from specklepy.core.api.inputs.project_inputs import ProjectModelsFilter
 from specklepy.core.api.models import Model, ModelWithVersions, ResourceCollection
+from specklepy.core.api.models.current import (
+    ModelPermissionChecks,
+    PermissionCheckResult,
+)
 from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse
 
@@ -299,3 +303,71 @@ class ModelResource(ResourceBase):
         return self.make_request_and_parse_response(
             DataResponse[DataResponse[Model]], QUERY, variables
         ).data.data
+
+    def get_permissions(self, project_id: str, model_id: str) -> ModelPermissionChecks:
+        QUERY = gql(
+            """
+            query ModelPermissions($projectId: String!, $modelId: String!) {
+              data:project(id: $projectId) {
+                data:model(id: $modelId) {
+                  data:permissions {
+                    canUpdate {
+                      authorized
+                      code
+                      message
+                    }
+                    canDelete {
+                      authorized
+                      code
+                      message
+                    }
+                    canCreateVersion {
+                      authorized
+                      code
+                      message
+                    }
+                  }
+                }
+              }
+            }
+            """
+        )
+
+        variables = {"projectId": project_id, "modelId": model_id}
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[DataResponse[ModelPermissionChecks]]],
+            QUERY,
+            variables,
+        ).data.data.data
+
+    def can_create_model_ingestion(
+        self, project_id: str, model_id: str
+    ) -> PermissionCheckResult:
+        QUERY = gql(
+            """
+            query ModelPermissions($projectId: String!, $modelId: String!) {
+              data:project(id: $projectId) {
+                data:model(id: $modelId) {
+                  data:permissions {
+                    data:canCreateIngestion {
+                      authorized
+                      code
+                      message
+                    }
+                  }
+                }
+              }
+            }
+            """
+        )
+
+        variables = {"projectId": project_id, "modelId": model_id}
+
+        return self.make_request_and_parse_response(
+            DataResponse[
+                DataResponse[DataResponse[DataResponse[PermissionCheckResult]]]
+            ],
+            QUERY,
+            variables,
+        ).data.data.data.data

src/specklepy/core/api/resources/current/subscription_resource.py

@@ -6,17 +6,25 @@ from graphql import DocumentNode
 from pydantic import BaseModel
 from typing_extensions import TypeVar
 
+from specklepy.core.api.enums import ProjectModelIngestionUpdatedMessageType
+from specklepy.core.api.inputs.model_ingestion_inputs import (
+    ModelIngestionReference,
+    ProjectModelIngestionSubscriptionInput,
+)
 from specklepy.core.api.models import (
     ProjectModelsUpdatedMessage,
     ProjectUpdatedMessage,
     ProjectVersionsUpdatedMessage,
     UserProjectsUpdatedMessage,
 )
+from specklepy.core.api.models.subscription_messages import (
+    ProjectModelIngestionUpdatedMessage,
+)
 from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse
 from specklepy.logging.exceptions import SpeckleException
 
-NAME = "subscribe"
+NAME = "subscription"
 
 TEventArgs = TypeVar("TEventArgs", bound=BaseModel)
 
@@ -202,6 +210,66 @@ class SubscriptionResource(ResourceBase):
             callback=lambda d: callback(d.data),
         )
 
+    async def project_model_ingestion_updated(
+        self,
+        callback: Callable[[ProjectModelIngestionUpdatedMessage], None],
+        input: ProjectModelIngestionSubscriptionInput,
+    ) -> None:
+        QUERY = gql(
+            """
+            subscription IngestionUpdated($input: ProjectModelIngestionSubscriptionInput!) {
+              data: projectModelIngestionUpdated(input: $input) {
+                modelIngestion {
+                  id
+                  createdAt
+                  updatedAt
+                  modelId
+                  cancellationRequested
+                  statusData {
+                    ... on HasModelIngestionStatus {
+                      status
+                    }
+                    ... on HasProgressMessage {
+                      progressMessage
+                    }
+                  }
+                }
+                type
+              }
+            }
+            """  # noqa: E501
+        )
+
+        variables = {
+            "input": input.model_dump(
+                warnings="error", by_alias=True, exclude_none=True
+            ),
+        }
+
+        await self.subscribe_2(
+            DataResponse[ProjectModelIngestionUpdatedMessage],
+            QUERY,
+            variables,
+            callback=lambda d: callback(d.data),
+        )
+
+    async def project_model_ingestion_cancellation_requested(
+        self,
+        callback: Callable[[ProjectModelIngestionUpdatedMessage], None],
+        project_id: str,
+        ingestion_id: str,
+    ) -> None:
+        await self.project_model_ingestion_updated(
+            callback,
+            ProjectModelIngestionSubscriptionInput(
+                project_id=project_id,
+                ingestion_reference=ModelIngestionReference(
+                    ingestion_id=ingestion_id, model_id=None
+                ),
+                message_type=ProjectModelIngestionUpdatedMessageType.CANCELLATION_REQUESTED,
+            ),
+        )
+
     @check_wsclient
     async def subscribe_2(
         self,

src/specklepy/core/api/resources/current/version_resource.py

@@ -14,7 +14,7 @@ from specklepy.core.api.models import ResourceCollection, Version
 from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse
 
-NAME = "model"
+NAME = "version"
 
 
 class VersionResource(ResourceBase):

src/specklepy/core/api/resources/current/workspace_resource.py

@@ -16,7 +16,7 @@ NAME = "workspace"
 
 
 class WorkspaceResource(ResourceBase):
-    """API Access class for models"""
+    """API Access class for workspaces"""
 
     def __init__(self, account, basepath, client, server_version) -> None:
         super().__init__(

src/specklepy/core/api/wrapper.py

@@ -1,8 +1,6 @@
 from urllib.parse import quote, unquote, urlparse
 from warnings import warn
 
-from gql import gql
-
 from specklepy.core.api.client import SpeckleClient
 from specklepy.core.api.credentials import (
     Account,
@@ -139,27 +137,11 @@ class StreamWrapper:
 
         if use_fe2 is True and self.branch_name is not None:
             self.model_id = self.branch_name
-            # get branch name
-            query = gql(
-                """
-                query Project($project_id: String!, $model_id: String!) {
-                    project(id: $project_id) {
-                        id
-                        model(id: $model_id) {
-                            name
-                        }
-                    }
-                }
-            """
-            )
-            self._client = self.get_client()
-            params = {"project_id": self.stream_id, "model_id": self.model_id}
-            project = self._client.httpclient.execute(query, params)
 
-            try:
-                self.branch_name = project["project"]["model"]["name"]
-            except KeyError as ke:
-                raise SpeckleException("Project model name is not found", ke) from ke
+            self._client = self.get_client()
+            model = self._client.model.get(self.model_id, self.stream_id)
+
+            self.branch_name = model.name
 
         if not self.stream_id:
             raise SpeckleException(
@@ -175,6 +157,10 @@ class StreamWrapper:
         """
         Gets an account object for this server from the local accounts db
         (added via Speckle Manager or a json file)
+
+        WARNING: this function will return ANY account for the server,
+          just because you pass a token in doesn't guarantee it will be used.
+          This whole class could do with a re-design...
         """
         if self._account and self._account.token:
             return self._account

src/specklepy/core/helpers/speckle_path_provider.py

@@ -88,6 +88,8 @@ def user_application_data_path() -> Path:
                     message="Cannot get appdata path from environment."
                 )
             return Path(app_data_path)
+        if sys.platform.startswith("darwin"):  # macOS
+            return _ensure_folder_exists(Path.home() / "Library", "Application Support")
         else:
             # try getting the standard XDG_DATA_HOME value
             # as that is used as an override
@@ -98,7 +100,7 @@ def user_application_data_path() -> Path:
                 return _ensure_folder_exists(Path.home(), ".config")
     except Exception as ex:
         raise SpeckleException(
-            message="Failed to initialize user application data path.", exception=ex
+            message="Failed to initialize user application data path."
         ) from ex
 
 

src/specklepy/logging/metrics.py

@@ -1,18 +1,20 @@
 import contextlib
 import getpass
 import hashlib
+import importlib.metadata
 import logging
 import platform
 import queue
 import sys
 import threading
+from typing import Any, Literal
 
 import requests
 
 from specklepy.core.api.credentials import Account
 
 """
-Anonymous telemetry to help us understand how to make a better Speckle.
+Lightweight usage telemetry to help us understand how to make a better Speckle.
 This really helps us to deliver a better open source project and product!
 """
 TRACK = True
@@ -21,28 +23,14 @@ HOST_APP_VERSION = f"python {'.'.join(map(str, sys.version_info[:2]))}"
 PLATFORMS = {"win32": "Windows", "cygwin": "Windows", "darwin": "Mac OS X"}
 
 LOG = logging.getLogger(__name__)
-METRICS_TRACKER = None
+METRICS_TRACKER: "MetricsTracker | None" = None
 
 # actions
 SDK = "SDK Action"
 CONNECTOR = "Connector Action"
 RECEIVE = "Receive"
 SEND = "Send"
-
-# not in use since 2.15
-ACCOUNTS = "Get Local Accounts"
-BRANCH = "Branch Action"
-CLIENT = "Speckle Client"
-COMMIT = "Commit Action"
-DESERIALIZE = "serialization/deserialize"
-INVITE = "Invite Action"
-OTHER_USER = "Other User Action"
-PERMISSION = "Permission Action"
-SERIALIZE = "serialization/serialize"
-SERVER = "Server Action"
-STREAM = "Stream Action"
-STREAM_WRAPPER = "Stream Wrapper"
-USER = "User Action"
+ACTIONS = Literal["SDK Action", "Connector Action", "Receive", "Send"]
 
 
 def disable():
@@ -62,46 +50,76 @@ def set_host_app(host_app: str, host_app_version: str | None = None):
 
 
 def track(
-    action: str,
+    action: ACTIONS,
     account: Account | None = None,
     custom_props: dict | None = None,
+    send_sync: bool = False,
+    track_email: bool = False,
 ):
+    """
+    :param action:
+    :type action: ACTIONS
+    :param account:
+    :type account: Account | None
+    :param custom_props:
+    :type custom_props: dict | None
+    :param send_sync: When `True`, the track event is executed synchronously,
+           and any exceptions will be raised.
+           When `False`, the track it is deferred to a queue, and any exceptions will be
+           swallowed and reported as warnings.
+    :type send_sync: bool
+    :param track_email: When `True`, the users plain text email address will be included
+    :type track_email: bool
+    """
     if not TRACK:
         return
+
+    tracker = initialise_tracker(account)
+
+    event_params: dict[str, Any] = {
+        "event": action,
+        "properties": {
+            "distinct_id": tracker.last_user,
+            "server_id": tracker.last_server,
+            "token": tracker.analytics_token,
+            "hostApp": HOST_APP,
+            "hostAppVersion": HOST_APP_VERSION,
+            "$os": tracker.platform,
+            "type": "action",
+        },
+    }
+    if custom_props:
+        event_params["properties"].update(custom_props)
+
+    if track_email:
+        event_params["properties"]["email"] = tracker.last_email
+
     try:
-        initialise_tracker(account)
-        event_params = {
-            "event": action,
-            "properties": {
-                "distinct_id": METRICS_TRACKER.last_user,
-                "server_id": METRICS_TRACKER.last_server,
-                "token": METRICS_TRACKER.analytics_token,
-                "hostApp": HOST_APP,
-                "hostAppVersion": HOST_APP_VERSION,
-                "$os": METRICS_TRACKER.platform,
-                "type": "action",
-            },
-        }
-        if custom_props:
-            event_params["properties"].update(custom_props)
+        specklepy_version = importlib.metadata.version("specklepy")
+        event_params["properties"]["core_version"] = specklepy_version
+    except importlib.metadata.PackageNotFoundError:
+        if send_sync:
+            raise
+        else:
+            LOG.warning("Failed to read specklepy's version number", exc_info=True)
 
-        METRICS_TRACKER.queue.put_nowait(event_params)
-    except Exception as ex:
-        # wrapping this whole thing in a try except as we never want a failure here
-        # to annoy users!
-        LOG.debug(f"Error queueing metrics request: {str(ex)}")
+    if send_sync:
+        tracker.send_event(event_params)
+    else:
+        tracker.queue_event(event_params)
 
 
-def initialise_tracker(account: Account | None = None):
+def initialise_tracker(account: Account | None = None) -> "MetricsTracker":
     global METRICS_TRACKER
     if not METRICS_TRACKER:
         METRICS_TRACKER = MetricsTracker()
 
-    if account and account.userInfo.email:
-        METRICS_TRACKER.set_last_user(account.userInfo.email)
-    if account and account.serverInfo.url:
+    if account:
+        METRICS_TRACKER.set_last_user_email(account.userInfo.email)
         METRICS_TRACKER.set_last_server(account.serverInfo.url)
 
+    return METRICS_TRACKER
+
 
 class Singleton(type):
     _instances = {}
@@ -113,48 +131,65 @@ class Singleton(type):
 
 
 class MetricsTracker(metaclass=Singleton):
-    analytics_url = "https://analytics.speckle.systems/track?ip=1"
-    analytics_token = "acd87c5a50b56df91a795e999812a3a4"
-    last_user = ""
-    last_server = None
-    platform = None
-    sending_thread = None
-    queue = queue.Queue(1000)
+    analytics_url: str = "https://analytics.speckle.systems/track?ip=1"
+    analytics_token: str = "acd87c5a50b56df91a795e999812a3a4"
+    last_user: str = ""
+    last_email: str = ""
+    last_server: str | None = None
+    platform: str
+
+    _sending_thread: threading.Thread
+    _queue: queue.Queue[dict[str, Any]] = queue.Queue(1000)
+    _session = requests.Session()
 
     def __init__(self) -> None:
-        self.sending_thread = threading.Thread(
+        self._sending_thread = threading.Thread(
             target=self._send_tracking_requests, daemon=True
         )
         self.platform = PLATFORMS.get(sys.platform, "linux")
-        self.sending_thread.start()
+        self._sending_thread.start()
         with contextlib.suppress(Exception):
             node, user = platform.node(), getpass.getuser()
             if node and user:
                 self.last_user = f"@{self.hash(f'{node}-{user}')}"
 
-    def set_last_user(self, email: str):
+    def set_last_user_email(self, email: str | None) -> None:
         if not email:
             return
         self.last_user = f"@{self.hash(email)}"
+        self.last_email = email
 
-    def set_last_server(self, server: str):
+    def set_last_server(self, server: str | None) -> None:
         if not server:
             return
         self.last_server = self.hash(server)
 
-    def hash(self, value: str):
+    @staticmethod
+    def hash(value: str) -> str:
         inputList = value.lower().split("://")
         input = inputList[len(inputList) - 1].split("/")[0].split("?")[0]
         return hashlib.md5(input.encode("utf-8")).hexdigest().upper()
 
-    def _send_tracking_requests(self):
-        session = requests.Session()
+    def queue_event(self, event_params: dict[str, Any]) -> None:
+        try:
+            self._queue.put_nowait(event_params)
+        except queue.Full:
+            LOG.warning(
+                "Metrics event was skipped because the metrics queue was was full",
+                exc_info=True,
+            )
+
+    def send_event(self, event_params: dict[str, Any]) -> None:
+        response = self._session.post(self.analytics_url, json=[event_params])
+        response.raise_for_status()
+
+    def _send_tracking_requests(self) -> None:
         while True:
-            event_params = [self.queue.get()]
+            event_params = self._queue.get()
 
             try:
-                session.post(self.analytics_url, json=event_params)
-            except Exception as ex:
-                LOG.debug(f"Error sending metrics request: {str(ex)}")
+                self.send_event(event_params)
+            except Exception:
+                LOG.warning("Error sending metrics request", exc_info=True)
 
-            self.queue.task_done()
+            self._queue.task_done()

src/specklepy/objects/base.py

@@ -323,6 +323,30 @@ def _validate_type(t: Optional[type], value: Any) -> Tuple[bool, Any]:
 
 @dataclass(kw_only=True)
 class Base(_RegisteringBase, speckle_type="Base"):
+    """Base class for all Speckle objects.
+
+    The base object class is the foundation of all data being
+    transferred with Speckle. Any custom data structure that you want to transfer via
+    Speckle should inherit from it.
+
+    Objects in Speckle are immutable for storage purposes. When any property changes,
+    the object gets a new identity (hash). This hash is stored in the `id` property
+    after serialization.
+
+    Attributes:
+        id: Unique identifier (hash) for the object. This is typically
+        set automatically during serialization and depends on the object's properties.
+        applicationId: Optional identifier for the application that created
+            this object, can store the host application's native object ID.
+
+    ```py title="Example"
+    from specklepy.objects.base import Base
+    obj = Base(id="some-id", applicationId="my-app")
+    obj["custom_prop"] = 42  # Add a dynamic property
+    obj["@detached_prop"] = another_object  # Add a detached property
+    ```
+    """
+
     id: Union[str, None] = None
     # totalChildrenCount: Union[int, None] = None
     applicationId: Union[str, None] = None