docs: conform with pypi and open external links in seperate tab (#13)

* docs: fix readme assets for proper display on pypi

* feat: version and system info from cli

Allows printing system info along with encord-agents version from the CLI
Also introduceds issue templates for people to report bugs, feature requestsion and suggestions for the documentation

* chore: update pip install to be just encord-agents

* docs: add batches

* chore: update pyproject to have richer pypi information

* docs: make all external links open in separate tab

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,31 @@
+name: 🐞 Bug Report
+description: Create a bug report to help us reproduce and fix the bug
+title: "bug: "
+labels: ["🐞❔ unconfirmed bug"]
+body:
+  - type: textarea
+    attributes:
+      label: Provide environment information
+      description: |
+        Run this command in your project root and paste the results:
+        ```bash
+        encord-agents print system-info
+        ```
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of the bug, as well as what you expected to happen when encountering it.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: To reproduce
+      description: Describe how to reproduce your bug. Steps, code snippets etc.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Add any other information related to the bug here, screenshots/videos if applicable.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: ❓ Simple question - Slack Chat
+    url: https://join.slack.com/t/encordactive/shared_invite/zt-1hc2vqur9-Fzj1EEAHoqu91sZ0CX0A7Q
+    about: This issue tracker is not for technical support. Please use our Slack chat and ask the community for help.

.github/ISSUE_TEMPLATE/documentation_issue.yml

@@ -0,0 +1,27 @@
+name: 📚 Documentation
+description: Help us improve our documentation
+title: "docs:"
+labels: ["📚 documentation"]
+body:
+  - type: textarea
+    attributes:
+      label: Documentation issue
+      description: Is this issue related to an existing part of the documentation? If so, please provide a link
+      placeholder: >
+        Helpful info about this issue.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Describe the thing to improve
+      description: A clear and concise description of problems and what you would like to see
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Describe the solution (optional)
+      description: Ideas about what we should do to improve experience of beginners and readers. It may be new pages to add, grammar fixes etc.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: 🧑‍💻 Feature Request
+description: Suggest an idea for this project
+title: "feat: "
+labels: ["🌟 enhancement"]
+body:
+  - type: textarea
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the solution you'd like to see
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe alternate solutions
+      description: A clear and concise description of any alternative solutions or features you've considered.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Add any other information related to the feature here. If your feature request is related to any issues or discussions, link them here.

README.md

@@ -6,7 +6,7 @@
 </p>
 
 <h1 align="center">
-  <a href="https://encord.com"><img src="docs/assets/landing-banner.png" alt="Encord logo"/></a>
+    <a href="https://encord.com"><img src="https://raw.githubusercontent.com/encord-team/encord-agents/main/docs/assets/landing-banner.png" alt="Encord logo"/></a>
 </h1>
 
 <div style="display: flex; justify-content: space-between;">
@@ -18,10 +18,10 @@
       <img alt="Encord Notebooks" src="https://img.shields.io/badge/Encord_Notebooks-blue?logo=github&label=&labelColor=181717">
     </a>
     <a href="https://colab.research.google.com/drive/1wvKAQ61JPebGnAT4nLXsfJRbx7dvtFdX?usp=sharing" target="_blank" style="text-decoration:none">
-      <img alt="Try editor agent" src="docs/assets/tag-colab-editor-agent.svg">
+            <img alt="Try editor agent" src="https://raw.githubusercontent.com/encord-team/encord-agents/main/docs/assets/tag-colab-editor-agent.svg">
     </a>
     <a href="https://colab.research.google.com/drive/1wvKAQ61JPebGnAT4nLXsfJRbx7dvtFdX?usp=sharing" target="_blank" style="text-decoration:none">
-      <img alt="Try task agent" src="docs/assets/tag-colab-task-agent.svg">
+            <img alt="Try task agent" src="https://raw.githubusercontent.com/encord-team/encord-agents/main/docs/assets/tag-colab-task-agent.svg">
     </a>
     <a href="https://join.slack.com/t/encordactive/shared_invite/zt-1hc2vqur9-Fzj1EEAHoqu91sZ0CX0A7Q" target="_blank" style="text-decoration:none">
       <img alt="Join us on Slack" src="https://img.shields.io/badge/Join_Our_Community-4A154B?label=&logo=slack&logoColor=white">
@@ -30,6 +30,14 @@
       <img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/encord_team?label=%40encord_team&amp;style=social">
     </a>
   </div>
+  <div style="flex: 1; padding: 10px;">
+    <img alt="Python versions" src="https://img.shields.io/pypi/pyversions/encord-agents">
+    <a href="https://pypi.org/project/encord-agents/" target="_blank" style="text-decoration:none">
+      <img alt="PyPi project" src="https://img.shields.io/pypi/v/encord-agents">
+    </a>
+    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-Welcome-blue">
+    <img alt="Licence" src="https://img.shields.io/github/license/encord-team/encord-agents">
+  </div>
 </div>
 
 Easily build agents for the Encord echo system.
@@ -46,7 +54,7 @@ With just few lines of code, you can take automation to the next level.
 
 Here are some use-cases:
 
-![Decision tree for which agent to use](docs/assets/decide-on-agent-type.png)
+![Decision tree for which agent to use](https://raw.githubusercontent.com/encord-team/encord-agents/main/docs/assets/decide-on-agent-type.png)
 
 Here's how to build an Agent:
 

docs/authentication.md

@@ -1,16 +1,16 @@
 To interact with the Encord platform, you need to authenticate.
 Please, follow these steps:
 
-1. Ensure that you have an Encord account. If you don't, you can [register here][register].
-2. Follow [this documentation][docs-auth] to obtain a public and private ssh key.
+1. Ensure that you have an Encord account. If you don't, you can [register here][register]{ target="\_blank", rel="noopener noreferrer" }.
+2. Follow [this documentation][docs-auth]{ target="\_blank", rel="noopener noreferrer" } to obtain a public and private ssh key.
    > 💡 Consider creating a service accounte for the purpose of creating agents.
 3. In the environment that you plan to run your agents, set either of these two environment variables:
    - `ENCORD_SSH_KEY`: Containing the raw private key file content
    - `ENCORD_SSH_KEY_FILE`: Containing the absolute path to the private key file
 
 If none of the env variables are set, the code will cast a pydantic validation error the first time it needs the ssh key.
 
-> ℹ️ Effectively, [this part][docs-ssh-key-access] of the `encord` SDK is used to perform authentication.
+> ℹ️ Effectively, [this part][docs-ssh-key-access]{ target="\_blank", rel="noopener noreferrer" } of the `encord` SDK is used to perform authentication.
 
 [register]: https://app.encord.com/register
 [docs-ssh-key-access]: https://docs.encord.com/sdk-documentation/sdk-references/EncordUserClient#create-with-ssh-private-key

docs/editor_agents/fastapi.md

@@ -24,7 +24,7 @@ source venv/bin/activate
 Install the dependencies.
 
 ```shell
-python -m pip install "fastapi[standard]" git+https://github.com/encord-team/encord-agents
+python -m pip install "fastapi[standard]" encord-agents
 ```
 
 ## Develop your agent
@@ -43,8 +43,8 @@ from fastapi.middleware.cors import CORSMiddleware
 
 app = FastAPI()
 app.add_middleware(
-            CORSMiddleware,
-            allow_origins=["*", "https://app.encord.com"],
+    CORSMiddleware,
+    allow_origins=["*", "https://app.encord.com"],
 )
 
 @app.post("/my_agent")
@@ -82,7 +82,7 @@ ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
     }
     ```
 
-To hit that agent endpoint, open the [Label Editor](https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor) in your browser on a frame for which you want to test your agent. Copy the URL.
+To hit that agent endpoint, open the [Label Editor](https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor){ target="\_blank", rel="noopener noreferrer" } in your browser on a frame for which you want to test your agent. Copy the URL.
 
 Open a new terminal in the `my_project` directory.
 Then, run

docs/editor_agents/gcp.md

@@ -27,7 +27,7 @@ Make a requirements file:
 
 ```requirements title="requirements.txt"
 functions-framework
-git+https://github.com/encord-team/encord-agents
+encord-agents
 ```
 
 Install the dependencies.
@@ -81,7 +81,7 @@ ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
     }
     ```
 
-To hit that agent endpoint, open the [Label Editor](https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor) in your browser on a frame for which you want to test your agent. Copy the URL.
+To hit that agent endpoint, open the [Label Editor](https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor){ target="\_blank", rel="noopener noreferrer" } in your browser on a frame for which you want to test your agent. Copy the URL.
 
 Open a new terminal in the `my_project` directory.
 Then, run
@@ -111,10 +111,10 @@ gcloud functions deploy my_agent \
 
 Notice how we set secrets (the ssh key that the agent should use).
 
-Here are the official [Google run function deploy docs](https://cloud.google.com/functions/docs/create-deploy-gcloud).
+Here are the official [Google run function deploy docs](https://cloud.google.com/functions/docs/create-deploy-gcloud){ target="\_blank", rel="noopener noreferrer" }.
 There are a couple of things that you need to pay attention to:
 
 - You must make sure to authenticate `gcloud` and select the appropriate project first
-- You should configure a secret with the ssh_key content. Please see [Google Secrets docs](https://cloud.google.com/functions/docs/configuring/secrets)
+- You should configure a secret with the ssh_key content. Please see [Google Secrets docs](https://cloud.google.com/functions/docs/configuring/secrets){ target="\_blank", rel="noopener noreferrer" }
 
 

docs/editor_agents/index.md

@@ -27,7 +27,7 @@ Some common use-cases are:
 
 - _Validate the current state of the annotations_ within a frame, video, or image group. You might, for example, want to give the labelers an option to annotate the current state of the labels before submitting.
 - Do _custom conversions or modifications_ of labels before they are submitted. For example, you could be simplifying polygons with an RDP algorithm.
-- Employ custom prompting models like [DINOv][dinov] or [T-Rex2][trex2] to speed up annotations.
+- Employ custom prompting models like [DINOv][dinov]{ target="\_blank", rel="noopener noreferrer" } or [T-Rex2][trex2]{ target="\_blank", rel="noopener noreferrer" } to speed up annotations.
 - _Trigger notifications_ internally related to the given task.
 
 Think of these agents as agents that your annotators can trigger at will _while they are labeling_.
@@ -56,11 +56,11 @@ That is, you will be responsible for programatically defining what to do, when y
 
 We help with two different ways of building such Custom APIs:
 
-1. Using [`Google run functions`][gcp-functions] which is Google's way of building cloud functions.
-2. Using [FastAPI][fastapi] which is a flexible (self-hosted) python library for building custom APIs.
+1. Using [`Google run functions`][gcp-functions]{ target="\_blank", rel="noopener noreferrer" } which is Google's way of building cloud functions.
+2. Using [FastAPI][fastapi]{ target="\_blank", rel="noopener noreferrer" } which is a flexible (self-hosted) python library for building custom APIs.
 
 !!! tip
-    Actually, the `encord-agents` take a lot of inspiration from [FastAPI][fastapi]. Specifically, we have adopted the idea of [dependency injections][fastapi-dependency-injection] from that library. While our [injection scheme](../dependencies.md) is not as sophisticated, it should feel familiar.
+    Actually, the `encord-agents` take a lot of inspiration from [FastAPI][fastapi]{ target="\_blank", rel="noopener noreferrer" }. Specifically, we have adopted the idea of [dependency injections][fastapi-dependency-injection]{ target="\_blank", rel="noopener noreferrer" } from that library. While our [injection scheme](../dependencies.md) is not as sophisticated, it should feel familiar.
 
 Google run functions are good for more light-weight operations like acting as proxies to other model inference APIs or tweaking labels.
 FastAPI apps are better suited for actually hosting your own models.

docs/getting_started.md

@@ -1,4 +1,4 @@
-> ℹ️ This example requires `python >= 3.10`. If you do not have python 3.10, we recommend using, e.g., [`pyenv`](https://github.com/pyenv/pyenv) to manage your python versions.
+> ℹ️ This example requires `python >= 3.10`. If you do not have python 3.10, we recommend using, e.g., [`pyenv`](https://github.com/pyenv/pyenv){ target="\_blank", rel="noopener noreferrer" } to manage your python versions.
 
 Here's the steps to follow to run your first [task agent](task_agents/index.md).
 The example agent will modify the priority of each task before passing it along.
@@ -23,12 +23,12 @@ source venv/bin/activate
 Now, install `encord-agents`.
 
 ```shell
-python -m pip install git+https://github.com/encord-team/encord-agents
+python -m pip install encord-agents
 ```
 
 ### 2. Encord workflow project
 
-If you don't already have a [workflow project][docs-workflow-project] which includes an [agent stage][docs-workflow-agent], please [create one][docs-create-project].
+If you don't already have a [workflow project][docs-workflow-project]{ target="\_blank", rel="noopener noreferrer" } which includes an [agent stage][docs-workflow-agent]{ target="\_blank", rel="noopener noreferrer" }, please [create one][docs-create-project]{ target="\_blank", rel="noopener noreferrer" }.
 
 In this example, we use a project workflow that looks like this:
 
@@ -61,7 +61,7 @@ if __name__ == "__main__":
     runner.run()
 ```
 
-Notice the `my_agent_logic`, it recieves a [`LabelRowV2`][lrv2-class] instance.
+Notice the `my_agent_logic`, it recieves a [`LabelRowV2`][lrv2-class]{ target="\_blank", rel="noopener noreferrer" } instance.
 That label row is associated with a task that is currently sitting in the `"pre-label"` agent stage.
 Also, the agent is returning the name of the pathway that the task is supposed to follow upon agent completion.
 

docs/index.md

@@ -25,7 +25,7 @@
 Easily build agents for the Encord echo system.
 With just few lines of code, you can take automation to the next level.
 
-For a [workflow][docs-workflow] with a prioritization agent node looking like this:
+For a [workflow][docs-workflow]{ target="\_blank", rel="noopener noreferrer" } with a prioritization agent node looking like this:
 
 ![](assets/examples/tasks_agents/prioritize_by_title_workflow.png)
 
@@ -39,12 +39,12 @@ Here's how to build a [Task Agent](task_agents/index.md) that prioritizes annota
 
 > 💡 For the full end-to-end example, please see [here](getting_started.md).
 
-This repository provides utility functions and examples for building both [editor agents][editor_agents] and [task agents][task_agents].
+This repository provides utility functions and examples for building both [editor agents][editor_agents]{ target="\_blank", rel="noopener noreferrer" } and [task agents][task_agents]{ target="\_blank", rel="noopener noreferrer" }.
 
 **Key features:**
 
 1. ⚡**Easy**: Multiple template agents to be adapted and hosted via GCP, own infra, or cloud.
-2. ⏩ **Convenient**: The library conveniently loads data via the [Encord SDK][encord_sdk] upon request.
+2. ⏩ **Convenient**: The library conveniently loads data via the [Encord SDK][encord_sdk]{ target="\_blank", rel="noopener noreferrer" } upon request.
 3. 👨‍💻 **Focus**: With essential resources readily available, you can focus on what matters. Create agents with pre-existing (or custom) dependencies for loading labels and data.
 4. 🤏 **Slim**: the library is slim at it's `core` and should not conflict with the dependencies of most projects.
 
@@ -60,17 +60,4 @@ Upon [installation](./installation.md) and [authentication](./authentication.md)
 [editor_agents]: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-editor-agents
 [task_agents]: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-task-agents
 [encord_sdk]: https://pypi.org/project/encord/
-[fastapi]: https://fastapi.tiangolo.com/
-[poetry]: https://python-poetry.org/
-[label_row_v2]: https://docs.encord.com/sdk-documentation/sdk-references/LabelRowV2
-[pipx]: https://github.com/pypa/pipx
-[frame-data-code]: https://github.com/encord-team/encord-agents/blob/main/encord_agents/core/data_model.py#L6
-[editor-agent]: https://github.com/encord-team/encord-agents/blob/main/encord_agents/gcp/wrappers.py#L65
-[docs-ssh-key-access]: https://docs.encord.com/sdk-documentation/sdk-references/EncordUserClient#create-with-ssh-private-key
-[docs-sdk-label]: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-working-with-labels
-[google-gcp-functions-docs]: https://cloud.google.com/functions/docs/create-deploy-gcloud
-[google-gcp-secrets-docs]: https://cloud.google.com/functions/docs/configuring/secrets
-[fastapi-deploy-docs]: https://fastapi.tiangolo.com/deployment/
-[colab-task-agent]: https://colab.research.google.com/drive/1nOVYEG-johzJK6R_mnkgjOiRJUuNIvOY?usp=sharing
-[colab-editor-agent]: https://colab.research.google.com/drive/1wvKAQ61JPebGnAT4nLXsfJRbx7dvtFdX?usp=sharing
 [docs-workflow]: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-workflow-projects#workflow-projects

docs/installation.md

@@ -1,10 +1,10 @@
 If you just want to install `encord-agents` in your current environment, you can run:
 
 ```shell
-python -m pip install git+https://github.com/encord-team/encord-agents
+python -m pip install encord-agents
 ```
 
-> ℹ️ This project requires `python >= 3.10`. If you do not have python 3.10, we recommend using, e.g., [`pyenv`](https://github.com/pyenv/pyenv) to manage your python versions.
+> ℹ️ This project requires `python >= 3.10`. If you do not have python 3.10, we recommend using, e.g., [`pyenv`](https://github.com/pyenv/pyenv){ target="\_blank", rel="noopener noreferrer" } to manage your python versions.
 
 ---
 
@@ -39,15 +39,15 @@ Now you should see the environment before the cursor in your terminal.
 Now install `encord-agents` as above:
 
 ```shell
-python -m pip install git+https://github.com/encord-team/encord-agents
+python -m pip install encord-agents
 ```
 
 ### Poetry
 
 If you already have a poetry project, you can also add `encord-agents` to that project:
 
 ```shell
-poetry add git+https://github.com/encord-team/encord-agents
+poetry add encord-agents
 ```
 
 ### Conda
@@ -73,11 +73,11 @@ Now you should see the environment before the cursor in your terminal.
 Then, install `encord-agents` within the environment:
 
 ```shell
-python -m pip install git+https://github.com/encord-team/encord-agents
+python -m pip install encord-agents
 ```
 
 ## Dependencies
 
 The dependencies of `encord-agents` are choosen to be lite.
 The only heavy dependencies that are somewhat heavy are `opencv-python` and `numpy`.
-To see the full list of dependencies, you can have a look [here](https://github.com/encord-team/encord-agents/blob/main/pyproject.toml).
+To see the full list of dependencies, you can have a look [here](https://github.com/encord-team/encord-agents/blob/main/pyproject.toml){ target="\_blank", rel="noopener noreferrer" }.

encord_agents/cli/gcp.py

@@ -27,7 +27,7 @@
 # TODO update encord-agents dependency
 _DEPENDENCIES = """
 functions-framework
-git+https://github.com/encord-team/encord_agents
+encord_agents
 """
 
 _TEMPLATE_CONTENT_W_ASSET = """