Getting Started

Installation

• Follow instructions here to install meganno-client

Self-hosted Service

• Download docker compose files at meganno-service
• Follow setup instructions here to launch meganno backend services

Authentication

We have 2 ways to authenticate with the service:

1. Short-term 1 hour access with username and password sign in.

   • Require re-authentication every hour.

   • After executing auth = Authentication(project="<project_name>", host=<"project_host">, port=<"project_port">) (this only works for notebook and terminal running on local computer), you will be provided with a sign in interface via a new browser tab.

   • After signing in, you will be able to generate a long-term personal access token by running auth.create_access_token(expiration_duration=7, note="testing")

     • expiration_duration is in days.
     • To have non-expiring token, set expiration_duration to 0 (under the hood, it still expires after 100 years).

2. Long-term access with access token without signing in every time.

   • If the notebook or terminal is running on the cloud, you need to use this method to authenticate with the service.
   • With the save token, you can initialize the authentication class object by executing:

     auth = Authentication(project="<project_name>", host=<"project_host">, port=<"project_port">, token="<your_token>")
     

Roles

MEGAnno supports 2 types of user roles: Admin and Contributor. Admin users are project owners deploying the services; they have full access to the project such as importing data or updating schemas. Admin users can invite contributors by sharing invitation code(s) with them. Contributors can only access their own annotation namespace and cannot modify the project.

To invite contributors, follow the instructions below:

1. Initialize Admin class object:

   from meganno_client import Admin
   token = "..."
   auth = Authentication(project="<project_name>", token=token)
   
   admin = Admin(project="eacl_demo", auth=auth)
   # OR
   admin = Admin(project="eacl_demo", token=token)
   

2. Genereate invitation code
   • invitation code has 7-day expiration duration

     admin.create_invitation(single_use=True, code="<invitation_code>", role_code="contributor")
     

3. To renew or revoke an existing invitation code:
   • after renewing, the expiration date is extended by another 7 days.

     admin.get_invitations()
     admin.renew_invitation(id="<invitation_code_id>")
     admin.revoke_invitation(id="<invitation_code_id>")
     

4. New users with valid invitation code can sign up by installing the client library and follow the instructions below:
   • After executing auth = Authentication(project="<project_name>"), a new browser tab will present itself.
   • Clicking on "Sign up" at the bottom of the dialog, and you will be taken to the sign up page.

Role Access

Method	Route	Role
GET POST	/agents	administrator contributor
GET	/agents/jobs /agents/<string:agent_uuid>/jobs
GET POST	/agents/<string:agent_uuid>/jobs/<string:job_uuid> /annotations/<string:record_uuid>	administrator contributor job
POST	/annotations/batch
	/annotations/<string:record_uuid>/labels	administrator contributor
	/annotations/label_metadata	administrator contributor job
GET POST	/assignments	administrator contributor
POST	/data /data/metadata	administrator
GET	/data/export /data/suggest_similar	administrator contributor
GET	/schemas	administrator contributor job
POST		administrator
POST	/verifications/<string:record_uuid>/labels	administrator contributor
GET	/annotations /view/record /view/annotation /view/verifications	administrator contributor job
	/reconciliations	administrator contributor
GET	/statistics/annotator/contributions /statistics/annotator/agreements /statistics/embeddings/<embed_type> /statistics/label/progress /statistics/label/distributions	administrator
GET POST PUT DELETE	/invitations	administrator
GET	/invitations/<invitation_code>
GET POST DELETE	/tokens	administrator contributor