Annotation synchronization by b-Tomas · Pull Request #56 · inorbit-ai/inorbit-connector-python

b-Tomas · 2026-01-19T21:47:28Z

Description

Adds a reusable annotation synchronization framework for synchronizing waypoints between external systems and InOrbit's Config API.

New annotation_sync module: Provides interfaces and manager for implementing annotation synchronization
- AnnotationSyncManager: Handles sync operations with InOrbit Config API
- ExternalAnnotationProvider and AnnotationConverter interfaces for custom implementations
New inorbit module: Extracted Config API client and models for reusability
- InOrbitConfigAPI: Client for Config API operations
- Models: ConfigObject, SpatialAnnotation, WaypointAnnotationSpec, etc.
Documentation: Comprehensive docs for annotation sync specification and usage
Tests: Added test suite for annotation sync functionality (test_waypoint_sync.py)
Examples: Updated fleet connector example with annotation sync implementation

Note

Introduces an experimental, framework-level annotation sync feature and a reusable Config API client, with integration points in the core connector and full docs/examples/tests.

Adds annotation_sync module: AnnotationSyncManager, ExternalAnnotationProvider, AnnotationConverter, per-frame sync lifecycle (auto-start on publish_robot_pose()), ownership via spec.properties.syncOrigin
Adds inorbit module: InOrbitConfigAPI (httpx-based), ConfigObject/SpatialAnnotation/Waypoint* models; exports via package __init__
Extends ConnectorConfig: new rest_api_url (reads INORBIT_REST_API_URL) and optional annotation_sync block; updates env var handling
Updates FleetConnector: registration API for sync, lazy per-frame_id manager creation, clean start/stop on connect/disconnect
Examples: fleet connector demonstrates mock waypoint sync; config (example.fleet.yaml) gains annotation_sync fields
Docs: new spec/usage pages for Annotation Sync and Config API; navigation updated
Tests: comprehensive unit tests for models, manager lifecycle, and integration
Misc: logging improvements in examples; adds httpx dependency

^{Written by Cursor Bugbot for commit 6ac1a36. This will update automatically on new commits. Configure here.}

Copilot

Pull request overview

This PR introduces an annotation synchronization framework that enables bidirectional synchronization of waypoint annotations between external fleet management systems and InOrbit's Config API. The implementation provides a reusable framework that any connector can use by implementing two simple interfaces.

Changes:

Adds annotation synchronization framework with pluggable provider/converter interfaces
Implements InOrbit Config API client for managing SpatialAnnotation objects
Integrates annotation sync into FleetConnector with per-frame_id manager creation
Includes comprehensive test suite with 1191 lines of tests covering lifecycle, sync modes, and edge cases
Adds documentation and working example implementation

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/test_waypoint_sync.py	Comprehensive test suite for annotation sync (config, models, API client, manager, lifecycle)
pyproject.toml	Adds httpx dependency for REST API client
inorbit_connector/models.py	Adds rest_api_url field and AnnotationSyncConfig to ConnectorConfig
inorbit_connector/inorbit/models.py	Defines Config API models (ConfigObject, SpatialAnnotation, WaypointAnnotationSpec)
inorbit_connector/inorbit/config_api.py	Implements InOrbitConfigAPI client for CRUD operations on config objects
inorbit_connector/inorbit/init.py	Exports Config API models and client
inorbit_connector/connector.py	Integrates annotation sync with FleetConnector (registration, per-frame managers, lifecycle)
inorbit_connector/annotation_sync/models.py	Defines AnnotationSyncConfig and AnnotationSyncMode enum
inorbit_connector/annotation_sync/manager.py	Implements AnnotationSyncManager for bidirectional synchronization
inorbit_connector/annotation_sync/interfaces.py	Defines Protocol interfaces (ExternalAnnotationProvider, AnnotationConverter)
inorbit_connector/annotation_sync/init.py	Exports annotation sync framework components
inorbit_connector/init.py	Re-exports InOrbit Config API models
examples/fleet-connector/waypoint_sync.py	Example implementation of provider and converter for mock external system
examples/fleet-connector/fleet_client.py	Updates frame_id to match example configuration
examples/fleet-connector/connector.py	Demonstrates annotation sync registration in connector
examples/example.fleet.yaml	Adds annotation_sync configuration section
examples/README.md	Documents annotation sync in fleet connector example
docs/*	Comprehensive documentation for annotation sync feature

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

inorbit_connector/connector.py

examples/fleet-connector/waypoint_sync.py

inorbit_connector/connector.py

tests/test_waypoint_sync.py

b-Tomas · 2026-01-23T14:04:43Z

@cursor review

Copilot

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

inorbit_connector/annotation_sync/manager.py

inorbit_connector/inorbit/models.py

pyproject.toml

tests/test_waypoint_sync.py

cursor

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

inorbit_connector/connector.py

tests/test_waypoint_sync.py

inorbit_connector/annotation_sync/manager.py

…arate concerns and reduce implementation size

…ormat code

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

miguelgarcia

Hey I made several suggestions. I have various doubts about the chosen names, how the inorbit -> robot sync work, and how this would work for multi-floor.

Anyway this is amazing progress :D

miguelgarcia · 2026-01-26T12:48:09Z

docs/contents/usage/annotation-sync.md

+class MyAnnotationConverter:
+    """Converts between positions and waypoint annotations."""
+
+    def position_to_annotation(


Again, I would just use annotation and not position. This could be robot_to_inorbit and inorbit_to_robot. That would make super clear the conversion direction without having to remember that a position is an annotation in the robot side.

miguelgarcia · 2026-01-26T12:49:41Z

inorbit_connector/connector.py

        # Update robot ID cache
        self.__robot_ids = [robot.robot_id for robot in self.config.fleet]

+    def register_annotation_sync(


nit. I think this should be plural register_annotations_sync

miguelgarcia · 2026-01-26T12:50:54Z

examples/fleet-connector/waypoint_sync.py

@@ -0,0 +1,135 @@
+# SPDX-FileCopyrightText: 2025 InOrbit, Inc.


I think this file should be waypoints_sync.py since it syncs waypointS, unless the name is only about the type of annotations being synced

I actually forgot to rename it to annotation_sync, like the library module. I'll name it annotations_sync.py

miguelgarcia · 2026-01-26T12:54:55Z

docs/contents/specification/annotation-sync.md

+- **Annotation**: An InOrbit `SpatialAnnotation` object. Currently, only waypoint annotations are supported.
+- **Position**: A waypoint/location in the external system.
+- **External system**: The software the connector interacts with (fleet manager, robot software).


After taking a look at the whole implementation I really don't like these names. Both Annotation and Position are really annotations that come from different sources. I also don't like "external", it depends on the user's side or pov.

I suggest using:

Annotation -> InOrbitAnnotation

Position -> RobotAnnotation

External -> Robot

External System -> Robot Software or Robot Management Software

Also, let's avoid using "location" since it already has a precise meaning in InOrbit.

I believe these names can bring a lot of clarity.

miguelgarcia · 2026-01-26T12:56:21Z

inorbit_connector/annotation_sync/models.py

+
+from pydantic import BaseModel, Field, model_validator
+
+ANNOTATION_SYNC_ORIGIN_PROPERTY = "syncOrigin"


Origin has a strong meaning when talking about spatial things. Perhaps we could use "source" or "owner"

miguelgarcia · 2026-01-26T13:02:51Z

inorbit_connector/annotation_sync/manager.py

+        )
+        return stats
+
+    async def sync_inorbit_to_external(self) -> dict:


sync_inorbit_to_robot

miguelgarcia · 2026-01-26T13:05:46Z

inorbit_connector/annotation_sync/manager.py

+        Fetches all annotations from InOrbit, filters for owned ones,
+        converts them to positions, and synchronizes with the external system.


I'm not sure this is how InOrbit to Robot should work. Without knowing anything I had thought that this should sync any waypoint defined in InOrbit for my location to the FMS, without worrying about the owner.

I imagine the user case would be that I define a waypoint in InOrbit and it gets copied to all FMSs.

I agree. Will switch to no filtering

miguelgarcia · 2026-01-26T13:07:21Z

inorbit_connector/annotation_sync/models.py

+        EXTERNAL_TO_INORBIT: Sync from external system to InOrbit
+            (external system is source of truth)
+        INORBIT_TO_EXTERNAL: Sync from InOrbit to external system
+            (InOrbit is source of truth)


More naming I'd name these ROBOT_TO_INORBIT AND INORBIT_TO_ROBOT

WDYT aboout FLEET_TO_INORBIT AND INORBIT_TO_FLEET? I find ROBOT to be too singular, when this feature is mostly going to be used to sync fleet managers with InOrbit

I like it. Also a robot is a fleet of one :)

miguelgarcia · 2026-01-26T13:09:11Z

inorbit_connector/inorbit/config_api.py

+                )
+
+        # Fetch existing objects
+        existing_objects = await self.list_objects(kind, scope)


Please check if the config API limits results or uses pagination

miguelgarcia · 2026-01-26T13:11:45Z

inorbit_connector/inorbit/models.py

+
+    x: float
+    y: float
+    theta: float


I think we are missing the frame id. How does this work for multi-floor ?

Managers are initialized per frame_id. In a multifloor environment, syncing starts as soon as a robot starts publishing a pose in a certain frame_id, and the annotation is applied to such frame_id.

This has the recently noted platform limitation of not being able to transform coordinates to a sublocation, which is the reason this module is "experimental" and should be until the platform fully supports multi-area annotations.

👍 I missed that. I thought there was a single sync manager for the whole location. I believe it should be like that. Why would we wait until a robot visits a floor before reporting the annotations ?

Because the connector is unaware of what frame_ids are ever going to be published and therefor managed unless explicitly and manually registered before hand, which is against the current design of all mutli-area connectors. Those connectors dynamically change the frame_id published based on robot data (e.g. frame_id is mapped to the map ID the robot is publishing). This reduces a lot of manual setup.

We could also switch to a manual approach, which would require implementing more logic in the client connector. The config file could have a list of frame_ids (the areas) but then use would need to reverse map that to whatever system an FMS would use.

b-Tomas · 2026-01-26T13:30:01Z

@miguelgarcia thanks for taking the time to review. I agree with the naming comments, and I'll take care of those.

As for the question comments, I hope I answered all of them. Please let me know your thoughts on each thread.

b-Tomas self-assigned this Jan 19, 2026

b-Tomas requested a review from Copilot January 23, 2026 01:48

b-Tomas marked this pull request as ready for review January 23, 2026 01:49

Copilot started reviewing on behalf of b-Tomas January 23, 2026 01:49 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

b-Tomas requested a review from Copilot January 23, 2026 14:04

Copilot started reviewing on behalf of b-Tomas January 23, 2026 14:05 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

inorbit_connector/annotation_sync/manager.py Show resolved Hide resolved

inorbit_connector/inorbit/models.py Show resolved Hide resolved

pyproject.toml Outdated Show resolved Hide resolved

tests/test_waypoint_sync.py Show resolved Hide resolved

cursor bot reviewed Jan 23, 2026

View reviewed changes

inorbit_connector/connector.py Outdated Show resolved Hide resolved

tests/test_waypoint_sync.py Outdated Show resolved Hide resolved

inorbit_connector/annotation_sync/manager.py Show resolved Hide resolved

b-Tomas requested a review from miguelgarcia January 23, 2026 14:54

b-Tomas force-pushed the b-Tomas/waypoint-sync branch from bc02be4 to 41a9127 Compare January 24, 2026 22:20

b-Tomas force-pushed the main branch from 8403fbf to 35b7052 Compare January 24, 2026 22:21

b-Tomas and others added 15 commits January 24, 2026 19:23

Initial implementation

c3215ee

Simplify by removing bidirectional sync and cleanup interfaces to sep…

b6b28c2

…arate concerns and reduce implementation size

Rename waypoint -> annotation

c46422e

Remove diabled state

bd639d6

Fix docs and an import. Docs still need review

b0a975a

Some documentation

7c92a15

Refactor for config API module reusabitliy, rewrite some docs and ref…

094ecdf

…ormat code

Fix some CLRF vs LF line ending issues

c70e733

Remove debug prints and fix a typo

b7c39d7

Fix race condition in sync manager initialization

cb67bbf

Fix annotation filter in manager sync

8830b67

Fix kind checking in config api sync method

0627bd7

Add missing validtor to AnnotationSyncConfig

a32abdf

Remove extra meaningless test

ba7f088

Update pyproject.toml

e4172ba

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

b-Tomas added 4 commits January 24, 2026 19:23

Fix potential race condition starting manages

de4b715

Fix the filter function for annotatoin sync

e699e05

Formatting

e0e6de5

Update docs

c43a839

b-Tomas force-pushed the b-Tomas/waypoint-sync branch from 41a9127 to c43a839 Compare January 24, 2026 22:23

Git renormalize

364994a

miguelgarcia requested changes Jan 26, 2026

View reviewed changes

b-Tomas marked this pull request as draft February 13, 2026 17:56

		@@ -0,0 +1,135 @@
		# SPDX-FileCopyrightText: 2025 InOrbit, Inc.


		from pydantic import BaseModel, Field, model_validator

		ANNOTATION_SYNC_ORIGIN_PROPERTY = "syncOrigin"

		Fetches all annotations from InOrbit, filters for owned ones,
		converts them to positions, and synchronizes with the external system.

Comments

Conversation

b-Tomas commented Jan 19, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

b-Tomas commented Jan 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

miguelgarcia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b-Tomas commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

b-Tomas commented Jan 19, 2026 •

edited by cursor bot

Loading