Add artifact support with ORAS to make them OCI format

.env.example

@@ -1,3 +1,4 @@
 # We use PG by default as the metadata database.
 METADATA_DB_URL=postgresql+psycopg2://user:pass@localhost:5432/mydb
+ARTIFACT_REGISTRY_URL=http://localhost:5000/
 LOG_LEVEL=INFO

.env.integration-test

@@ -0,0 +1,3 @@
+METADATA_DB_URL=sqlite:///:memory:
+ARTIFACT_REGISTRY_URL=europe-west2-docker.pkg.dev/runsandbox-449400/
+LOG_LEVEL=INFO

.env.test

@@ -0,0 +1,3 @@
+METADATA_DB_URL=sqlite:///:memory:
+ARTIFACT_REGISTRY_URL=localhost:5000
+LOG_LEVEL=INFO

.github/workflows/python-ci.yaml

@@ -25,7 +25,9 @@ jobs:
         run: poetry config virtualenvs.in-project true
 
       - name: Install dependencies
-        run: poetry install --no-interaction --no-ansi
+        run: poetry install --with dev --no-interaction --no-ansi
+
+      # Lint is already included in `make test`
 
       - name: Run tests
         run: make test

.gitignore

@@ -9,6 +9,7 @@ Dockerfile.cross
 
 # Test binary, build with `go test -c`
 *.test
+!.env.test
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out

Makefile

@@ -12,11 +12,15 @@ publish: build
 launch:
 	docker-compose up -d
 
-.PHONY: test
-test:
-	$(POETRY) run pytest
-
 .PHONY: format
 format:
-	ruff format .
-	ruff check --fix .
+	$(POETRY) run ruff format .
+	$(POETRY) run ruff check .
+
+.PHONY: test
+test: format
+	$(POETRY) run pytest tests/unit
+
+.PHONY: test-integration
+test-integration: format
+	$(POETRY) run pytest tests/integration

README.md

@@ -2,6 +2,24 @@
 
 **AlphaTrion** is an open-source and all-in-one platform to build LLM-powered applications. Named after the wise Transformer mentor, it embodies guidance and innovation to help developers build **production-ready** GenAI applications with ease. *Still under active development.*
 
+## How to Install
+
+### Install from PyPI
+
+```bash
+pip install alphatrion
+```
+
+### Install from Source
+
+Refer to [developer.md](./docs/development.md) for more information on how to set up your development environment.
+
+## Quick Start
+
+Still under active development now.
+
+Refer to [troubleshooting.md](./docs/troubleshooting.md) for common issues and solutions which may help.
+
 ## How to Contribute
 
 We welcome all kinds of contributions! Please see our [contribution guidelines](CONTRIBUTING.md) for more details.

alphatrion/artifact/artifact.py

@@ -0,0 +1,46 @@
+import os
+
+import oras.client
+
+from alphatrion import consts
+from alphatrion.runtime.runtime import Runtime
+
+SUCCESS_CODE = 201
+
+
+class Artifact:
+    def __init__(self, runtime: Runtime):
+        self._runtime = runtime
+        self._url = os.environ.get(consts.ARTIFACT_REGISTRY_URL)
+        self._url = self._url.replace("https://", "").replace("http://", "")
+        self._client = oras.client.OrasClient(
+            hostname=self._url.strip("/"), auth_backend="token"
+        )
+
+    def push(self, experiment_name: str, files: list[str], version: str = "latest"):
+        url = self._url if self._url.endswith("/") else f"{self._url}/"
+
+        target = f"{url}{self._runtime._project_id}/{experiment_name}:{version}"
+
+        try:
+            self._client.push(target, files=files)
+        except Exception as e:
+            raise RuntimeError("Failed to push artifacts") from e
+
+    def list_tags(self, experiment_name: str) -> list[str]:
+        url = self._url if self._url.endswith("/") else f"{self._url}/"
+        target = f"{url}{self._runtime._project_id}/{experiment_name}"
+        try:
+            tags = self._client.get_tags(target)
+            return tags
+        except Exception as e:
+            raise RuntimeError("Failed to list artifacts tags") from e
+
+    def delete_tags(self, experiment_name: str, versions: str | list):
+        url = self._url if self._url.endswith("/") else f"{self._url}/"
+        target = f"{url}{self._runtime._project_id}/{experiment_name}"
+
+        try:
+            self._client.delete_tags(target, tags=versions)
+        except Exception as e:
+            raise RuntimeError("Failed to delete tags") from e

alphatrion/consts.py

@@ -1 +1,2 @@
 METADATA_DB_URL = "METADATA_DB_URL"
+ARTIFACT_REGISTRY_URL = "ARTIFACT_REGISTRY_URL"

alphatrion/experiment/base.py

@@ -27,6 +27,10 @@ def delete(self, exp_id: int):
     def get(self, exp_id: int):
         raise NotImplementedError("Subclasses must implement this method.")
 
+    @abstractmethod
+    def list(self, page: int = 0, page_size: int = 10):
+        raise NotImplementedError("Subclasses must implement this method.")
+
     @abstractmethod
     def update_labels(self, exp_id: int, labels: dict):
         raise NotImplementedError("Subclasses must implement this method.")

alphatrion/experiment/custom_exp.py

@@ -30,6 +30,11 @@ def delete(self, exp_id: int):
     def get(self, exp_id: int):
         return self._runtime._metadb.get_exp(exp_id=exp_id)
 
+    def list(self, page: int = 0, page_size: int = 10):
+        return self._runtime._metadb.list_exps(
+            project_id=self._runtime._project_id, page=page, page_size=page_size
+        )
+
     # Please provide all the labels to update, or it will overwrite the existing labels.
     def update_labels(self, exp_id: int, labels: dict):
         self._runtime._metadb.update_exp(exp_id=exp_id, labels=labels)

docs/development.md

@@ -10,7 +10,7 @@
 We welcome contributions! Please follow these steps:
 
 1. Fork the repository.
-2. Run `eval $(poetry env activate)` to activate the virtual environment.
+2. Run `source start.sh` to activate the virtual environment.
 3. Install dependencies with `poetry install`.
 4. Make your changes.
 

docs/troubleshooting.md

@@ -0,0 +1,14 @@
+# Troubleshooting
+
+## Common Issues and Solutions
+
+1. Failed to push the artifacts to the artifact registry:
+   - Ensure that the `ARTIFACT_REGISTRY_URL` environment variable is correctly set in your `.env` file, it looks like:
+     ```
+     ARTIFACT_REGISTRY_URL=https://gcr.io/alphatrion/
+     ```
+   - Verify that you have the necessary permissions to push to the specified registry and the repository exists.
+   - For cloud user and local deployment, we use credential helper to authenticate. For example for google cloud, please make sure you have installed Google Cloud SDK and run the following command to configure Docker authentication:
+     ```bash
+     gcloud auth configure-docker gcr.io
+     ```