[SYNPY-1544] Synapse Agent OOP Model (#1152)

* Adds async convenience functions

* expose convenience functions

* updates convenience functions

* updates agent_services

* removes rest_get_async exception handling

* pre-commit fixes

* delete accidentally committed script

* adds initial agent implementation

* clean up agent

* adds missing docstrings

* pre-commit

* updates agent_services

* updates agent.py

* Updates alias ID handling

* adds syncronous interface

* prevent cicular import in storable_entity_components

* remove promt sending and receiving from agent_service

* adds initial (dirty) async job mixin

* pre-commit run

* [SYNPY-1544] potential changes to mixin (#1153)

* Changes for async mixin

* Remove arg

* bug fix

* generalizes send_job_and_wait_async

* removes typing.Self

---------

Co-authored-by: bwmac <[email protected]>

* cleans up agent logic

* adds async job unit tests

* updates async job tests

* adds agent unit tests

* adds integration tests

* pre-commit

* adds examples to agent.py

* removes todos

* adds POC script

* add to mixins

* adds agent docs

* updates agent docs

* reorganize documentation

* updates poc script

* clean up

* add docstring

* removes unused imports

* split too long lines

* force synapse_client kwarg

* updates agent.py

* updates synapse_client docstring description

* updates asynchronous_job

* updates integration tests

* pre-commit

* agent inherited members

* updates docs for inherited members

* missing inherited members

* updates doc formatting

* try team formatting change

* updates script description

* adds Annotation lazy import

* try team formatting change

* more formatting changes

* address review comments in agent.py

* move synchronous docs up a layer

* adds syn login

* adds warning message to docs

* updates docstring examples

* updates docstrings

* adds error handling for agent.get

* async integration tests

* fix conditional

* disables integration tests

* updates docstring for clarity

---------

Co-authored-by: BryanFauble <[email protected]>

docs/reference/experimental/async/activity.md

@@ -0,0 +1,24 @@
+# Activity
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.Activity
+    options:
+      members:
+        - from_parent_async
+        - store_async
+        - delete_async
+---
+::: synapseclient.models.UsedEntity
+    options:
+      filters:
+      - "!"
+---
+::: synapseclient.models.UsedURL
+    options:
+      filters:
+      - "!"

docs/reference/experimental/async/agent.md

@@ -0,0 +1,32 @@
+# Agent
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API reference
+
+::: synapseclient.models.Agent
+    options:
+        members:
+            - register_async
+            - get_async
+            - start_session_async
+            - get_session_async
+            - prompt_async
+            - get_chat_history
+---
+::: synapseclient.models.AgentSession
+    options:
+        members:
+            - start_async
+            - get_async
+            - update_async
+            - prompt_async
+---
+::: synapseclient.models.AgentPrompt
+    options:
+        inherited_members: true
+        members:
+            - send_job_and_wait_async
+---

docs/reference/experimental/async/file.md

@@ -0,0 +1,27 @@
+# File
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.File
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - copy_async
+        - delete_async
+        - from_id_async
+        - from_path_async
+        - change_metadata_async
+        - get_permissions_async
+        - get_acl_async
+        - set_permissions_async
+---
+::: synapseclient.models.file.FileHandle
+    options:
+      filters:
+      - "!"

docs/reference/experimental/async/folder.md

@@ -0,0 +1,20 @@
+# Folder
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.Folder
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - delete_async
+        - copy_async
+        - sync_from_synapse_async
+        - get_permissions_async
+        - get_acl_async
+        - set_permissions_async

docs/reference/experimental/async/project.md

@@ -0,0 +1,19 @@
+# Project
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API reference
+
+::: synapseclient.models.Project
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - delete_async
+        - sync_from_synapse_async
+        - get_permissions_async
+        - get_acl_async
+        - set_permissions_async

docs/reference/experimental/async/table.md

@@ -0,0 +1,21 @@
+# Table
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.Table
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_schema_async
+        - store_rows_from_csv_async
+        - delete_rows_async
+        - query_async
+        - delete_async
+        - get_permissions_async
+        - get_acl_async
+        - set_permissions_async

docs/reference/experimental/async/team.md

@@ -0,0 +1,19 @@
+# Team
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.Team
+    options:
+        members:
+            - create_async
+            - delete_async
+            - from_id_async
+            - from_name_async
+            - members_async
+            - invite_async
+            - open_invitations_async
+---

docs/reference/experimental/async/user_profile.md

@@ -0,0 +1,19 @@
+# UserProfile
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.UserProfile
+    options:
+      inherited_members: true
+      members:
+      - get_async
+      - from_id_async
+      - from_username_async
+      - is_certified_async
+---
+::: synapseclient.models.UserPreference
+---

docs/reference/experimental/mixins/access_controllable.md

@@ -0,0 +1,3 @@
+# AccessControllable
+
+::: synapseclient.models.mixins.AccessControllable

docs/reference/experimental/mixins/asynchronous_communicator.md

@@ -0,0 +1,3 @@
+# AsynchronousCommunicator
+
+::: synapseclient.models.mixins.AsynchronousCommunicator

docs/reference/experimental/mixins/failure_strategy.md

@@ -0,0 +1,3 @@
+# FailureStrategy
+
+::: synapseclient.models.FailureStrategy

docs/reference/experimental/mixins/storable_container.md

@@ -0,0 +1,3 @@
+# StorableContainer
+
+::: synapseclient.models.mixins.StorableContainer

docs/reference/experimental/sync/activity.md

@@ -0,0 +1,35 @@
+# Activity
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## Example Script
+
+<details class="quote">
+  <summary>Working with activities</summary>
+
+```python
+{!docs/scripts/object_orientated_programming_poc/oop_poc_activity.py!}
+```
+</details>
+
+## API Reference
+
+::: synapseclient.models.Activity
+    options:
+      inherited_members: true
+      members:
+        - from_parent
+        - store
+        - delete
+---
+::: synapseclient.models.UsedEntity
+    options:
+      filters:
+      - "!"
+---
+::: synapseclient.models.UsedURL
+    options:
+      filters:
+      - "!"

docs/reference/experimental/sync/agent.md

@@ -0,0 +1,42 @@
+# Agent
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## Example Script:
+
+<details class="quote">
+  <summary>Working with Synapse agents</summary>
+
+```python
+{!docs/scripts/object_orientated_programming_poc/oop_poc_agent.py!}
+```
+</details>
+
+## API Reference
+
+::: synapseclient.models.Agent
+    options:
+        inherited_members: true
+        members:
+            - register
+            - get
+            - start_session
+            - get_session
+            - prompt
+            - get_chat_history
+---
+::: synapseclient.models.AgentSession
+    options:
+        inherited_members: true
+        members:
+            - start
+            - get
+            - update
+            - prompt
+---
+::: synapseclient.models.AgentPrompt
+    options:
+        inherited_members: true
+---

docs/reference/experimental/sync/file.md

@@ -0,0 +1,37 @@
+# File
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## Example Script
+
+<details class="quote">
+  <summary>Working with files</summary>
+
+```python
+{!docs/scripts/object_orientated_programming_poc/oop_poc_file.py!}
+```
+</details>
+
+## API Reference
+
+::: synapseclient.models.File
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - copy
+        - delete
+        - from_id
+        - from_path
+        - change_metadata
+        - get_permissions
+        - get_acl
+        - set_permissions
+---
+::: synapseclient.models.file.FileHandle
+    options:
+      filters:
+      - "!"

docs/reference/experimental/sync/folder.md

@@ -0,0 +1,30 @@
+# Folder
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## Example Script
+
+<details class="quote">
+  <summary>Working with folders</summary>
+
+```python
+{!docs/scripts/object_orientated_programming_poc/oop_poc_folder.py!}
+```
+</details>
+
+## API Reference
+
+::: synapseclient.models.Folder
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - delete
+        - copy
+        - sync_from_synapse
+        - get_permissions
+        - get_acl
+        - set_permissions

docs/reference/experimental/sync/project.md

@@ -0,0 +1,29 @@
+# Project
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## Example Script
+
+<details class="quote">
+  <summary>Working with a project</summary>
+
+```python
+{!docs/scripts/object_orientated_programming_poc/oop_poc_project.py!}
+```
+</details>
+
+## API reference
+
+::: synapseclient.models.Project
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - delete
+        - sync_from_synapse
+        - get_permissions
+        - get_acl
+        - set_permissions