diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..a5f2881 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6c12782 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/documentation_issue.yml b/.github/ISSUE_TEMPLATE/documentation_issue.yml new file mode 100644 index 0000000..ba4ddcf --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..a1738ba --- /dev/null +++ b/.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. diff --git a/README.md b/README.md index 85fe9a8..fe03c4d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

- Encord logo + Encord logo

@@ -18,10 +18,10 @@ Encord Notebooks - Try editor agent + Try editor agent - Try task agent + Try task agent Join us on Slack @@ -30,6 +30,14 @@ Twitter Follow
+
+ Python versions + + PyPi project + + PRs Welcome + Licence +
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: diff --git a/docs/authentication.md b/docs/authentication.md index e77cbcd..b5c8595 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,8 +1,8 @@ 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 @@ -10,7 +10,7 @@ Please, follow these steps: 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 diff --git a/docs/editor_agents/fastapi.md b/docs/editor_agents/fastapi.md index 3d39a1a..170fdf2 100644 --- a/docs/editor_agents/fastapi.md +++ b/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 diff --git a/docs/editor_agents/gcp.md b/docs/editor_agents/gcp.md index 77ef8bc..1d8f891 100644 --- a/docs/editor_agents/gcp.md +++ b/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" } diff --git a/docs/editor_agents/index.md b/docs/editor_agents/index.md index b3b3e68..2c3055b 100644 --- a/docs/editor_agents/index.md +++ b/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. diff --git a/docs/getting_started.md b/docs/getting_started.md index 648a0bb..3602973 100644 --- a/docs/getting_started.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index aa204d1..0e9be59 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/installation.md b/docs/installation.md index 056de72..d6d2bee 100644 --- a/docs/installation.md +++ b/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,7 +39,7 @@ 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 @@ -47,7 +47,7 @@ python -m pip install git+https://github.com/encord-team/encord-agents 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" }. diff --git a/encord_agents/cli/gcp.py b/encord_agents/cli/gcp.py index c77964e..52095b2 100644 --- a/encord_agents/cli/gcp.py +++ b/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 = """ diff --git a/encord_agents/cli/main.py b/encord_agents/cli/main.py index edf2139..36e61a5 100644 --- a/encord_agents/cli/main.py +++ b/encord_agents/cli/main.py @@ -13,7 +13,19 @@ from .gcp import app as gcp_app from .test import app as test_app +from .print import app as print_app app = typer.Typer(rich_markup_mode="rich") app.add_typer(gcp_app, name="gcp") app.add_typer(test_app, name="test") +app.add_typer(print_app, name="print") + +@app.callback(invoke_without_command=True) +def version(version_: bool = typer.Option(False, "--version", "-v", "-V", help="Print the current version of Encord Agents")): + if version_: + import rich + from encord_agents import __version__ as ea_version + + rich.print(f"[purple]encord-agents[/purple] version: [green]{ea_version}[/green]") + exit() + diff --git a/encord_agents/cli/print.py b/encord_agents/cli/print.py new file mode 100644 index 0000000..74cdf02 --- /dev/null +++ b/encord_agents/cli/print.py @@ -0,0 +1,29 @@ +import sys +from typer import Typer + +app = Typer( + name="print", + help="Utility to print system info, e.g., for bug reporting.", + rich_markup_mode="rich", + no_args_is_help=True, +) + + +@app.command(name="system-info") +def print_system_info(): + """ + [bold]Prints[/bold] the information of the system for the purpose of bug reporting. + """ + import platform + print("System Information:") + uname = platform.uname() + print(f"\tSystem: {uname.system}") + print(f"\tRelease: {uname.release}") + print(f"\tMachine: {uname.machine}") + print(f"\tProcessor: {uname.processor}") + print(f"\tPython: {sys.version}") + + import encord_agents + print(f"encord-agents version: {encord_agents.__version__}") + + diff --git a/pyproject.toml b/pyproject.toml index ac211c2..fc17d42 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,10 +1,45 @@ [tool.poetry] name = "encord-agents" version = "v0.1.0" -description = "A framework for easily producing custom agens for your Encord Workflows." -authors = ["Encord Team"] +description = "A framework for producing custom agens for the Encord echosystem." +authors = ["Cord Technologies Limited "] +classifiers = [ + "Environment :: Console", + "Environment :: Web Environment", + "Intended Audience :: Developers", + "Intended Audience :: Education", + "Intended Audience :: Information Technology", + "Intended Audience :: Science/Research", + "Operating System :: OS Independent", + "Topic :: Scientific/Engineering", + "Topic :: Scientific/Engineering :: Artificial Intelligence", + "Topic :: Scientific/Engineering :: Information Analysis", + "Topic :: Software Development", + "Topic :: Software Development :: Quality Assurance", + "Programming Language :: Python", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", +] +documentation = "https://agents-docs.encord.com" +homepage = "https://encord.com" +keywords = [ + "encord", + "agent", + "agents", + "machine", + "learning", + "data", + "label", + "model", + "quality", + "test", + "automation", +] readme = "README.md" -packages = [{ include = "encord_agents" }] +repository = "https://github.com/encord-team/encord-agents" +license = "Apache-2.0" + [tool.poetry.dependencies] # CLI-only dependencies @@ -31,7 +66,7 @@ mkdocs = "^1.6.1" mkdocs-material = "^9.5.40" mkdocs-glightbox = "^0.4.0" ruff = "^0.6.9" -mkdocs-codeinclude-plugin = {git = "https://github.com/frederik-encord/mkdocs-codeinclude-plugin.git"} +mkdocs-codeinclude-plugin = { git = "https://github.com/frederik-encord/mkdocs-codeinclude-plugin.git" } mkdocs-git-revision-date-localized-plugin = "^1.3.0"