diff --git a/docs/README.md b/docs/README.md index b1540ec..093c2a2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,43 +1,3 @@ ---- -description: Giza CLI 0.17.0 ---- - # Giza CLI -Welcome to Giza CLI! - -This CLI provides the utilities to interact with Giza using the terminal. - -## πŸ€” What capabilities does the CLI offer? - -The CLI will serve as the main entrypoint for Giza Platform for developers. It aims to provide a tool to ease the managing of resources that exists in Giza Platform. - -For now it provides the following capabilities: - -* User related utilities, like `create`, `login` (JWT Authentication) and `create_api_key` (API Key Authentication) -* Model transpilation with `transpile` using multiple frameworks, like Cairo or EZKL -* Model versioning -* Proof generation for multiple frameworks, like Orion Cairo or EZKL -* Deployment of models to the Giza Platform as an endpoint for verifiable inferences -* Workspace management to help you with Giza Actions -* Actions jumpstart with `new` command to help you get started with your actions - -In the future each new resource added to Giza will have its corresponding capability in the CLI. - -## ✨ What's new? - -For a detailed list of changes, please refer to the [CHANGELOG](../CHANGELOG.md) file. - -## πŸ’– Join the community! - -Join the community and help build a safer and transparent AI in our [Discord](https://discord.gg/Kt24CsMb5k)! - -## ✍️ Authors & contributors - -For a full list of all authors and contributors, see [the contributors page](https://github.com/gizatechxyz/giza-cli/graphs/contributors). - -## License - -This project is licensed under the **MIT license**. - -See [LICENSE](../LICENSE/) for more information. +Please refer to the [updated documentation](https://docs.gizatech.xyz/), as the one you are consulting is outdated. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index cf54d6e..348c990 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,57 +3,3 @@ ## πŸš€ Welcome * [Giza CLI](README.md) -* [Installation](welcome/installation.md) -* [Authentication](welcome/authentication.md) -* [Frameworks](welcome/frameworks.md) -* [Actions](welcome/actions.md) - -## πŸ“¦ Resources - -* [Users](resources/users.md) -* [Models](resources/models.md) -* [Versions](resources/versions.md) -* [Workspaces](resources/workspaces.md) -* [Endpoints](resources/endpoints.md) -* [Agents](resources/agents.md) - -## πŸ“š Frameworks - -* [Cairo](frameworks/cairo/README.md) - * [Transpile](frameworks/cairo/transpile.md) - * [Deploy](frameworks/cairo/deploy.md) - * [Prove](frameworks/cairo/prove.md) - * [Verify](frameworks/cairo/verify.md) -* [EZKL](frameworks/ezkl/README.md) - * [Transpile](frameworks/ezkl/transpile.md) - * [Deploy](frameworks/ezkl/deploy.md) - * [Prove](frameworks/ezkl/prove.md) - * [Verify](frameworks/ezkl/verify.md) - -## πŸ“– Examples - -* [Basic Cairo CLI Example](examples/basic.md) -* [Reset Your Password](examples/reset\_password.md) - -## 🧱 Reference - -* [API Overview](reference/api/README.md) - * [callbacks](reference/api/callbacks.md) - * [cli](reference/api/cli.md) - * [client](reference/api/client.md) - * [commands](reference/api/commands.md) - * [commands.deploy](reference/api/commands.deploy.md) - * [commands.models](reference/api/commands.models.md) - * [commands.prove](reference/api/commands.prove.md) - * [commands.reset\_password](reference/api/commands.reset\_password.md) - * [commands.transpile](reference/api/commands.transpile.md) - * [commands.users](reference/api/commands.users.md) - * [commands.version](reference/api/commands.version.md) - * [commands.versions](reference/api/commands.versions.md) - * [commands.workspaces](reference/api/commands.workspaces.md) - * [exceptions](reference/api/exceptions.md) - * [options](reference/api/options.md) - * [utils.decorators](reference/api/utils.decorators.md) - * [utils.echo](reference/api/utils.echo.md) - * [utils.enum](reference/api/utils.enum.md) - * [utils](reference/api/utils.md) diff --git a/docs/examples/basic.md b/docs/examples/basic.md deleted file mode 100644 index 86343c0..0000000 --- a/docs/examples/basic.md +++ /dev/null @@ -1,116 +0,0 @@ -# Basic Cairo CLI Example - -For this example we will create a user, retrieve information from it and transpile a model. - -## Create User - -This is the first step! We create the user and then we need to verify the account by checking the email. - -```console -> giza users create - -Enter your username 😎: my-username -Enter your password πŸ₯· : (this is a secret) -Enter your email πŸ“§: gonzalo@gizatech.xyz -[giza][2023-06-23 12:29:40.543] Creating user in Giza βœ… -[giza][2023-06-23 12:29:41.417] User created βœ…. Check for a verification email πŸ“§ -``` - -Then we need to verify the email. We just need to click on the button and we'll be redirected to the verification endpoint. - -## Login - -If it is not verified login will be disabled! - -```console -> giza users login - -Enter your username 😎: my-username -Enter your password πŸ₯· : -[giza][2023-06-23 12:32:17.917] Log into Giza -[giza][2023-06-23 12:32:18.716] ⛔️Could not authorize the user⛔️ -[giza][2023-06-23 12:32:18.718] ⛔️Status code -> 400⛔️ -[giza][2023-06-23 12:32:18.719] ⛔️Error message -> {'detail': 'Inactive user'}⛔️ -``` - -But once we verify the account we will be able to authenticate with Giza. - -```console -> giza users login - -Enter your username 😎: my-username -Enter your password πŸ₯· : -[giza][2023-06-23 12:34:33.576] Log into Giza -[giza][2023-06-23 12:34:34.400] Successfully logged into Giza βœ… -``` - -## Retrieve user information - -Now that we are authenticated we can connect with Giza! - -```console -> giza users me - -[giza][2023-06-23 12:35:33.287] Retrieving information about me! -{ - "username": "my-username", - "email": "gonzalo@gizatech.xyz", - "is_active": true -} -``` - -## Create API Key - -You can also create an API key for the current user. This API key will be stored and will be used to authenticate the user in the future. - -```console -> giza users create-api-key -[giza][2024-01-17 15:27:27.936] Creating API Key βœ… -[giza][2024-01-17 15:27:53.605] API Key written to: /Users/gizabrain/.giza/.api_key.json -[giza][2024-01-17 15:27:53.606] Successfully created API Key. It will be used for future requests βœ… -``` - -**NOTE: The usage of API key is less secure than JWT, so use it with caution.** - -## Transpiling a Model - -Now that we have our `onnx` model, it's time to transpile it into a format that's compatible with `giza`. Transpilation is a process where we convert the model from one format to another without changing its underlying functionality. In this case, we're converting our `onnx` model into a `cairo` model. This is a crucial step as it allows us to leverage the power of `giza` and its ecosystem. - -But don't worry, `giza` makes this process a breeze with a simple command! Let's dive into it. - -```console -> giza transpile awesome_model.onnx --output-path cairo_model -[giza][2024-02-07 16:31:20.844] No model id provided, checking if model exists βœ… -[giza][2024-02-07 16:31:20.845] Model name is: awesome_model -[giza][2024-02-07 16:31:21.599] Model Created with id -> 1! βœ… -[giza][2024-02-07 16:31:22.436] Version Created with id -> 1! βœ… -[giza][2024-02-07 16:31:22.437] Sending model for transpilation βœ… -[giza][2024-02-07 16:32:13.511] Transpilation is fully compatible. Version compiled and Sierra is saved at Giza βœ… -[giza][2024-02-07 16:32:13.516] Transpilation recieved! βœ… -[giza][2024-02-07 16:32:14.349] Transpilation saved at: cairo_model -``` - -As you can see from the console output, if the model does not previously exist, `giza` will automatically create one for you. It assigns a unique id to the new model, in this case, the id is 25. This is indicated by the line `[giza][2024-02-07 16:31:21.599] Model Created with id -> 1! βœ…`. - -After the model is created, `giza` will create a new version for it `[giza][2024-02-07 16:31:22.436] Version Created with id -> 1! βœ…` and send it for transpilation. This is indicated by the line `[giza][2024-02-07 16:31:22.437] Sending model for transpilation βœ…`. The transpiled model is then saved at the specified output path. - -This feature of `giza` makes it easy to manage and version your models. You don't have to worry about manually creating a new model or version, `giza` handles it for you. - -Additionally, `giza` provides an option to specify the model id while transpiling. If you already have a model and want to create a new version for it, you can use the `--model-id` option followed by the id of the model. This will create a new version for the existing model instead of creating a new model. Here's how you can do it: - -Now let's check the result: - -```console -> tree cairo_model - -cairo_model -β”œβ”€β”€ inference -β”‚ β”œβ”€β”€ Scarb.toml -β”‚ └── src -β”‚ └── lib.cairo -└── initializers - β”œβ”€β”€ node_l1 - β”‚ β”œβ”€β”€ Scarb.toml - β”‚ └── src - β”‚ └── lib.cairo -``` diff --git a/docs/examples/reset_password.md b/docs/examples/reset_password.md deleted file mode 100644 index e4c127c..0000000 --- a/docs/examples/reset_password.md +++ /dev/null @@ -1,35 +0,0 @@ -# Reset Password Example - -In case you forget your password, Giza provides a secure and straightforward way to reset it. The process involves two main steps: - -## Request a Reset Token - -The first step is to request a reset token. This token will be sent to your registered email address. You can request a reset token by running the following command: - -```console -> giza request-reset-password-token --email your_email@example.com - -[giza][2023-08-30 12:53:18.423] Password recovery email sent -[giza][2023-08-30 12:53:18.428] Please check your email for a password reset token πŸ“¬ -``` - -The reset token is a unique string of characters that is used to verify your identity and allow you to change your password. It is only valid for a short period of time for security reasons. If you do not use it within this time, you will need to request a new one. - -## Reset Password - -Once you have received your reset token, you can use it to reset your password. Run the following command, replacing `your_reset_token` with the token you received in your email: - -```console -> giza reset-password --token your_reset_token - -Please enter your new password πŸ”‘: # Your new password goes here -Please confirm your new password πŸ”‘: -[giza][2023-08-30 12:55:32.128] Password updated successfully -[giza][2023-08-30 12:55:32.132] Password reset was successful πŸŽ‰ -``` - -With the above steps, you have successfully reset your password. Remember, it's important to keep your password secure and not share it with anyone. If you suspect that your password has been compromised, repeat the steps above to reset it. - -In case you encounter any issues or need further assistance, feel free to reach out to our support team. We're here to help! - -Stay secure! πŸ”’ diff --git a/docs/frameworks/cairo/README.md b/docs/frameworks/cairo/README.md deleted file mode 100644 index ab5bbd7..0000000 --- a/docs/frameworks/cairo/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Cairo - -Cairo is a programming language specifically designed for creating verifiable and efficient smart contracts and cryptographic proofs. Its core strength lies in its ability to create succinct and secure programs while ensuring formal verification of their correctness. - -In the realm of Giza, Cairo serves as the backbone for generating provable machine learning models. Leveraging Cairo as the backend provides a reliable infrastructure to transpile, prove and verify these models within the Giza platform. - -## Cairo Framework Features - -1. Transpilation Process: Dive into Giza's streamlined process to seamlessly convert ONNX machine learning models into Cairo code. This transformation ensures optimal compatibility and functionality within the Cairo ecosystem, leveraging the power of [✨Orion✨](https://github.com/gizatechxyz/orion). More on this in the [transpile documentation for cairo](transpile.md). -2. Creating Verifiable Proofs: Use the transpile model to generate the `casm.json` file to create a proof and validate the correctness and reliability of your transformed models. Discover how Giza harnesses Cairo's robust features to create evidence ensuring the credibility of your machine learning outputs. More on this in the [prove documentation for cairo](prove.md). - -[Cairo official documentation](https://docs.cairo-lang.org/) diff --git a/docs/frameworks/cairo/deploy.md b/docs/frameworks/cairo/deploy.md deleted file mode 100644 index 02a599d..0000000 --- a/docs/frameworks/cairo/deploy.md +++ /dev/null @@ -1,140 +0,0 @@ -# Deploy - -To deploy a model, you must first have a version of that model. If you have not yet created a version, please refer to the [versions](../../resources/versions.md) documentation. - -To create a new service, users can employ the `deploy` command. This command facilitates the deployment of a machine learning service ready to accept predictions at the `/cairo_run` endpoint, providing a straightforward method for deploying and using machine learning capabilities that can easily be consumed as and API endpoint. - -``` -> giza endpoints deploy --model-id 1 --version-id 1 model.sierra.json -β–°β–°β–°β–°β–°β–±β–± Creating endpoint! -[giza][2024-02-07 12:31:02.498] Endpoint is successful βœ… -[giza][2024-02-07 12:31:02.501] Endpoint created with id -> 1 βœ… -[giza][2024-02-07 12:31:02.502] Endpoint created with endpoint URL: https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app πŸŽ‰ -``` - -If a model is fully compatible the sierra file is not needed and can be deployed without using it in the command: - -``` -> giza endpoints deploy --model-id 1 --version-id 1 -β–°β–°β–°β–°β–°β–±β–± Creating endpoint! -[giza][2024-02-07 12:31:02.498] Endpoint is successful βœ… -[giza][2024-02-07 12:31:02.501] Endpoint created with id -> 1 βœ… -[giza][2024-02-07 12:31:02.502] Endpoint created with endpoint URL: https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app πŸŽ‰ -``` - -{% hint style="danger" %} -For a partially compatible model, the sierra file must be provided, if not an error will be shown. -{% endhint %} - -### Example request - -Now our service is ready to accept predictions at the provided endpoint URL. To test this, we can use the `curl` command to send a POST request to the endpoint with a sample input. - -``` -> curl -X POST https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app/cairo_run \ - -H "Content-Type: application/json" \ - -d '{ - "args": "[2 2] [1 2 3 4]" - }' | jq -{ - "result": [0.1234], - "request_id": "b14bfbcf250b404192765d9be0811c9b" -} -``` - -There is an extra args, `job_size`, that can be used in each request to specify the size of the proving job so it has more CPU and memory available to generate the proof. An example: - -``` -> curl -X POST https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app/cairo_run \ - -H "Content-Type: application/json" \ - -d '{ - "args": "[2 2] [1 2 3 4]", - "job_size": "M" - }' -``` - -Available sizes are `S`, `M`, `L,` and `XL`, each with different usage limits. - -## List the proving jobs for an endpoint - -To list the proving jobs for an endpoint, we can use the `list-jobs` command available for the endpoints. This command will return a list of all the proving jobs for the endpoint with the `request_id` for easier tracking. - -```console -> giza endpoints list-jobs --endpoint-id 1 -[giza][2024-03-06 18:13:50.485] Getting jobs from endpoint 1 βœ… -[ - { - "id": 1, - "job_name": "proof-20240306-979342e7", - "size": "S", - "status": "Completed", - "elapsed_time": 120., - "created_date": "2024-03-06T16:12:31.295958", - "last_update": "2024-03-06T16:14:29.952678", - "request_id": "979342e7b94641f0a260c1997d9ccfee" - }, - { - "id": 2, - "job_name": "proof-20240306-f6559749", - "size": "S", - "status": "COMPLETED", - "elapsed_time": 120.0, - "created_date": "2024-03-06T16:43:27.531250", - "last_update": "2024-03-06T16:45:17.272684", - "request_id": "f655974900d8479c9bb662a060bc1365" - } -] -``` - -## List the proofs for an endpoint - -To list the proofs for an endpoint, we can use the `list-proofs` command available for the endpoints. This command will return a list of all the proofs for the endpoint with the `request_id` for easier tracking. - -```console -> giza endpoints list-proofs --endpoint-id 1 -[giza][2024-03-06 18:15:23.146] Getting proofs from endpoint 32 βœ… -[ - { - "id": 1, - "job_id": 1, - "metrics": { - "proving_time": 0.03023695945739746 - }, - "created_date": "2024-03-06T16:44:46.196186", - "request_id": "979342e7b94641f0a260c1997d9ccfee" - }, - { - "id": 1, - "job_id": 2, - "metrics": { - "proving_time": 0.07637895945739746 - }, - "created_date": "2024-03-06T16:44:46.196186", - "request_id": "f655974900d8479c9bb662a060bc1365" - } -] -``` - -## Verify a proof - -After successfully creating a proof for your Orion Cairo model, the next step is to verify its validity. Giza offers a verification method using the `verify` command alongside the `endpoint-id` and `proof-id`. - -```console -> giza endpoints verify --endpoint-id 1 --proof-id "b14bfbcf250b404192765d9be0811c9b" -[giza][2024-02-20 15:40:48.560] Verifying proof... -[giza][2024-02-20 15:40:49.288] Verification result: True -[giza][2024-02-20 15:40:49.288] Verification time: 2.363822541 -``` - -This way we can easily and quickly verify the proof generated for our model. - -## Download the proof - -We can download the proof using the `download-proof` command available for the endpoints: - -
❯ giza endpoints download-proof --model-id 1 --version-id 1 --endpoint-id 1 --proof-id "b14bfbcf250b404192765d9be0811c9b"
-[giza][2024-02-20 15:40:48.560] Getting proof from endpoint 1 βœ…
-[giza][2024-02-20 15:40:49.288] Proof downloaded to zk.proof βœ…
-
- -The `proof id` used is the `request_id` returned in the response. diff --git a/docs/frameworks/cairo/prove.md b/docs/frameworks/cairo/prove.md deleted file mode 100644 index dc56a8e..0000000 --- a/docs/frameworks/cairo/prove.md +++ /dev/null @@ -1,59 +0,0 @@ -# Prove - -Giza provides two methods for proving Orion Cairo programs: through the CLI or directly after running inference on the Giza Platform. Below are detailed instructions for both methods - -## Option 1: Prove a Model After Running Inference - -**Deploying Your Model** - -After deploying your model on the Giza Platform, you will receive a URL for your deployed model. Refer to the [Endpoints section](../../resources/endpoints.md) for more details on deploying models. - -**Running Inference** - -To run inference, use the `/cairo_run` endpoint of your deployed model's URL. For example: - -``` -https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app/cairo_run -``` - -This action will execute the inference, generate Trace and Memory files on the platform, and initiate a proving job. The inference process will return the output result along with a request ID. - -**Checking Proof Status** - -To check the status of your proof, use the following command: - -``` -giza endpoints get-proof --model-id --version-id --endpoint-id --proof-id -``` - -**Downloading Your Proof** - -Once the proof is ready, you can download it using: - -``` -giza endpoints download-proof --model-id --version-id --endpoint-id --proof-id --output-path -``` - -{% hint style="info" %} -You can find an extensive example in [Giza Action tutorial](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions#run-and-prove) -{% endhint %} - -## Option 2: Proving a Model Directly from the CLI - -Alternatively, you can prove a model directly using the CLI without deploying the model for inference. This method requires providing Trace and Memory files, which can only be obtained by running [CairoVM](https://github.com/lambdaclass/cairo-vm) in proof mode. - -**Running the Prove Command** - -Execute the following command to prove your model: - -``` -giza prove --trace --memory --output-path -``` - -{% hint style="info" %} -This option is less preferred due to the necessity of dealing with CairoVM. -{% endhint %} - -{% hint style="danger" %} -If you opt for this method, ensure you use the following commit of CairoVM: `1a78237`. -{% endhint %} diff --git a/docs/frameworks/cairo/transpile.md b/docs/frameworks/cairo/transpile.md deleted file mode 100644 index 3cf61bb..0000000 --- a/docs/frameworks/cairo/transpile.md +++ /dev/null @@ -1,315 +0,0 @@ -# Transpile - -Transpilation is a crucial process in the deployment of Verifiable Machine Learning models. It involves the transformation of an ONNX model into a Cairo model. These models can generate proofs that can be verified, ensuring the integrity and reliability of the model's predictions. - -The transpilation of an ONNX model to a Cairo model is powered by [✨Orion✨](https://github.com/gizatechxyz/orion) - -The transpilation process begins by reading the model from the specified path. The model is then sent for transpilation. By default, the output of this process is saved in the `cairo_model/` folder. However, you can specify a different output path using the `--output-path` option. - -{% code overflow="wrap" %} -```console -> giza transpile awesome_model.onnx --output-path my_awesome_model -[giza][2024-02-07 16:31:20.844] No model id provided, checking if model exists βœ… -[giza][2024-02-07 16:31:20.845] Model name is: awesome_model -[giza][2024-02-07 16:31:21.599] Model Created with id -> 1! βœ… -[giza][2024-02-07 16:31:22.436] Version Created with id -> 1! βœ… -[giza][2024-02-07 16:31:22.437] Sending model for transpilation βœ… -[giza][2024-02-07 16:32:13.511] Transpilation is fully compatible. Version compiled and Sierra is saved at Giza βœ… -[giza][2024-02-07 16:32:13.516] Transpilation recieved! βœ… -[giza][2024-02-07 16:32:14.349] Transpilation saved at: my_awesome_model -``` -{% endcode %} - -The result of the transpilation process is saved at the provided path, in this case, `my_awesome_model/`. - -```console -> tree my_awesome_model/ -my_awesome_model -β”œβ”€β”€ inference -β”‚ β”œβ”€β”€ Scarb.toml -β”‚ └── src -β”‚ └── lib.cairo -└── initializers - β”œβ”€β”€ node_l1 - β”‚ β”œβ”€β”€ Scarb.toml - β”‚ └── src - β”‚ └── lib.cairo -``` - -When we transpile a model we have two possibilities: a fully compatible model and a partially compatible one. - -A model is fully compatible when all the operators that the model uses are supported by the Transpiler and Orion, if this happens the model is compiled after transpilation and we save the .sierra.json file on behalf of the user to use later for deployment ([endpoint docs](../../resources/endpoints.md)). This will be shown in the output of the transpile command: - -{% code overflow="wrap" %} -``` -[giza][2024-02-07 16:32:13.511] Transpilation is fully compatible. Version compiled and Sierra is saved at Giza βœ… -``` -{% endcode %} - -If a model is partially supported, we will create a warning in the output stating that not all the operators are supported right now. If it is partially supported the Cairo code can still be modified for later compilation and endpoint. - -{% code overflow="wrap" %} -``` -[WARN][2024-02-07 16:42:31.209] πŸ”Ž Transpilation is partially supported. Some operators are not yet supported in the Transpiler/Orion -[WARN][2024-02-07 16:42:31.211] Please check the compatibility list in Orion: https://cli.gizatech.xyz/frameworks/cairo/transpile#supported-operators -``` -{% endcode %} - -## Supported Operators - -| Operator | Implemented | -| :--------------------: | :------------------: | -| Abs | :white\_check\_mark: | -| Acos | :white\_check\_mark: | -| Acosh | :white\_check\_mark: | -| Add | :white\_check\_mark: | -| And | :white\_check\_mark: | -| Div | :white\_check\_mark: | -| Mul | :white\_check\_mark: | -| Sub | :white\_check\_mark: | -| Argmax | :white\_check\_mark: | -| Argmin | :white\_check\_mark: | -| Asin | :white\_check\_mark: | -| Asinh | :white\_check\_mark: | -| Atan | :white\_check\_mark: | -| Relu | :white\_check\_mark: | -| Constant | :white\_check\_mark: | -| MatMul | :white\_check\_mark: | -| Gemm | :white\_check\_mark: | -| TreeEnsembleClassifier | :white\_check\_mark: | -| LinearClassifier | :white\_check\_mark: | -| LinearRegressor | :white\_check\_mark: | -| Softmax | :white\_check\_mark: | -| Sigmoid | :white\_check\_mark: | -| Concat | :white\_check\_mark: | -| Squeeze | :white\_check\_mark: | -| Unsqueeze | :white\_check\_mark: | -| Reshape | :white\_check\_mark: | - -## How do we transpile a model? - -There are three main methods for transpiling a model: - -### **Method 1: Using the `giza transpile` command** - -``` - giza transpile awesome_model.onnx --output-path my_awesome_model -``` - -This is the simplest method and is recommended for most users.\ -When you run this command, Giza handles everything for you: - -* It first checks if a model with the specified name already exists. If not, it creates a new model and then transpiles it. -* The output of this process is saved in the `cairo_model/` folder by default, but you can specify a different output path using the `--output-path` option. - -This is the strategy that we followed in the example before. - -### **Method 2: Manually creating a model and then transpiling it** - -This method gives you more control over the process. - -1. First, you create a model manually using the `giza models create` command. -2. After the model is created, you can transpile it using the `giza transpile --model-id ...` - -This method is useful when you want to specify particular options or parameters during the model creation and transpilation process. - -```console -> giza models create --name awesome_model --description "A Model for testing different models" -[giza][2023-09-13 14:04:59.532] Creating model βœ… -{ - "id": 2, - "name": "awesome_model", - "description": "A Model for testing different models" -} -``` - -```console -> giza transpile --model-id 2 awesome_model.onnx --output-path new_awesome_model -[giza][2023-09-13 14:08:38.022] Model found with id -> 2! βœ… -[giza][2024-02-07 14:08:38.432] Version Created with id -> 1! βœ… -[giza][2023-09-13 14:08:38.712] Sending model for transpilation βœ… -[giza][2023-09-13 14:08:49.879] Transpilation recieved! βœ… -[giza][2023-09-13 14:08:49.885] Transpilation saved at: new_awesome_model -``` - -### **Method 3: Using a previous model** - -If you have a previously created model, you can transpile it by indicating the model-id in the `giza transpile --model-id ...` or `giza versions transpile --model-id` command. - -* This method is useful when you want to create a new version of an existing model. -* The output of the transpilation process is saved in the same location as the original model. - -```console -# Using the previous model (id: 2) we can transpile a new model, which will create version 2 of the model. -giza transpile --model-id 29 awesome_model.onnx --output-path new_awesome_model -[giza][2023-09-13 14:11:30.015] Model found with id -> 2! βœ… -[giza][2024-02-07 14:11:30.225] Version Created with id -> 2! βœ… -[giza][2023-09-13 14:11:30.541] Sending model for transpilation βœ… -[giza][2023-09-13 14:11:41.601] Transpilation recieved! βœ… -[giza][2023-09-13 14:11:41.609] Transpilation saved at: new_awesome_model -``` - -## Transpilation Results - -When a version is transpiled the version can be in the following statuses: - -* `FAILED`: the transpilation of the model failed -* COMPLETED: the version transpilation is completed and the version is FULLY compatible. This means that the version operators all are supported during transpilation and Orion, and the model has been compiled to sierra and saved in the platform. The model can be directly deployed without the need to provide a sierra file. This model is "frozen" so it will not allow for code or model updates and if any changes are done to the model a new version should be created. -* `PARTIALLY_SUPPORTED`: not all the operators are supported in the transpilation but they might be supported in Orion, so a partially working code will be returned, allowing for modifications of the code to update the version into a fully compatible one. Once this version is updated we will compile the version and if it is successful the new code and the sierra will be uploaded to Giza, the status will be updated to `COMPLETED` and the version will be frozen not allowing any more modifications. - -{% hint style="warning" %} -We try to support all the available operators on Orion but there might be a little lag between Orion's implementation and transpilation availability -{% endhint %} - -## How to update a transpilation - -If your model version is in a `PARTIALLY_SUPPORTED` status, you can work towards achieving a `COMPLETED` status by updating the transpilation. The update process involves modifying the unsupported operators and compiling the model. Here's how to update a transpilation, from creation to fully supported: - -1. Transpile the model with `giza transpile` -2. Modify your cairo model to address the unsupported operators. -3. Execute the giza version update command. This command needs `scarb` to be installed ([docs](https://docs.swmansion.com/scarb/)), compilation will be attempted and if successful code and sierra file will be updated in Giza. - -#### Example: Updating a Version - -Say you have an `awesome_model.onnx` that is `PARTIALLY_SUPPORTED`: - -
❯ giza transpile awesome_model.onnx
-[giza][2024-02-12 13:19:55.957] No model id provided, checking if model exists βœ… 
-[giza][2024-02-12 13:19:55.958] Model name is: awesome_model
-[giza][2024-02-12 13:19:56.207] Model Created with id -> 1! βœ…
-[giza][2024-02-12 13:19:56.710] Version Created with id -> 1! βœ…
-[giza][2024-02-12 13:19:56.711] Sending model for transpilation βœ… 
-[WARN][2024-02-12 13:20:07.207] πŸ”Ž Transpilation is partially supported. Some operators are not yet supported in the Transpiler/Orion
-[WARN][2024-02-12 13:20:07.209] Please check the compatibility list in Orion: https://cli.gizatech.xyz/frameworks/cairo/transpile#supported-operators
-[giza][2024-02-12 13:20:07.773] Downloading model βœ…
-[giza][2024-02-12 13:20:07.783] model saved at: cairo_model
-
- -This version has some operators that are not available in the transpilation, but they might be supported in Orion. When a model is not fully compatible, in the `inference/lib.cairo` a comment will be shown: - -{% code overflow="wrap" %} -``` -let node_8 = // Operator LogSoftmax is not yet supported by the Giza transpiler. If Orion supports it, consider manual implementation.; -``` -{% endcode %} - -Let's say that `LogSoftMax` is the unsupported operator, if we check the Orion Documentation, we can see that it [is supported](https://orion.gizatech.xyz/framework/operators/neural-network/nn.logsoftmax). Now we could add the necessary code to add our operator (including imports): - -``` -let node_8 = NNTrait::logsoftmax(node_7_output_0, 1); -``` - -{% hint style="warning" %} -LogSoftMax serves as an example and does not mean that it is not currently supported -{% endhint %} - -After the manual implementation, we can trigger the update with the `update` command: - -{% code overflow="wrap" %} -``` -❯ giza versions update --model-id 1 --version-id 1 --model-path cairo_model -[giza][2024-02-12 13:35:28.993] Checking version βœ… -scarb 2.4.3 (5dbab1f31 2024-01-04) -cairo: 2.4.3 (https://crates.io/crates/cairo-lang-compiler/2.4.3) -sierra: 1.4.0 - -[giza][2024-02-12 13:35:29.138] Scarb is installed, proceeding with the build. - Compiling inference v0.1.0 (/Users/gizabrain/cairo_model/inference/Scarb.toml) -error: Unexpected argument type. Expected: "@orion::operators::tensor::core::Tensor::", found: "orion::operators::tensor::core::Tensor::". - --> /Users/gizabrain/cairo_model/inference/src/lib.cairo:15:34 -let node_8 = NNTrait::logsoftmax(node_7_output, 1); - ^********************^ - - -error: could not compile `inference` due to previous error -[ERROR][2024-02-12 13:35:34.847] Compilation failed -[ERROR][2024-02-12 13:35:34.848] ⛔️Error building the scarb model⛔️ -[ERROR][2024-02-12 13:35:34.848] ⛔️Version could not be updated⛔️ -[ERROR][2024-02-12 13:35:34.849] Check scarb documentation https://docs.swmansion.com/scarb/ -``` -{% endcode %} - -Here's what is going on: - -* We want to update the first version of the first model with our new code, the code is at `--model-path cairo_model` -* The CLI checks if `scarb` is available in the system -* `scarb build` is attempted -* We still have some errors that we have to fix - -In this case, we purposely forgot to add the `@`to showcase a common scenario: - -``` -let node_8 = NNTrait::logsoftmax(@node_7_output, 1); -``` - -Once everything is fixed we can attempt the update again: - -``` -❯ giza versions update --model-id 1 --version-id 1 --model-path cairo_model -[giza][2024-02-12 13:43:25.913] Checking version βœ… -scarb 2.4.3 (5dbab1f31 2024-01-04) -cairo: 2.4.3 (https://crates.io/crates/cairo-lang-compiler/2.4.3) -sierra: 1.4.0 - -[giza][2024-02-12 13:43:26.064] Scarb is installed, proceeding with the build. - Compiling inference v0.1.0 (/Users/gizabrain/cairo_model/inference/Scarb.toml) - Finished release target(s) in 6 seconds -[giza][2024-02-12 13:43:32.326] Compilation successful -[giza][2024-02-12 13:43:33.708] Sierra updated βœ… -[giza][2024-02-12 13:43:34.962] Version updated βœ… -{ - "version": 1, - "size": 8858, - "status": "COMPLETED", - "message": null, - "description": "Initial version", - "created_date": "2024-02-12T12:19:56.324501", - "last_update": "2024-02-12T12:43:34.906667" -} -``` - -The version has been updated successfully! Now we have a fully compatible model that generated a sierra and can be easily deployed! Now the version will be frozen so it won't allow for any more updates. - -{% hint style="info" %} -When we refer to a version of a model, we refer to the code/artifact of a specific model at a specific point in time. The model is frozen for tracking purposes. -{% endhint %} - -## What is happening with the models and versions? - -In Giza, a model is essentially a container for versions. Each version represents a transpilation of a machine learning model at a specific point in time. This allows you to keep track of different versions of your model as it evolves and improves over time. - -To check the current models and versions that have been created, you can use the following steps: - -1. Use the `giza models list` command to list all the models that have been created. -2. For each model, you can use the `giza versions list --model-id ...` command to list all the versions of that model. - -Remember, each version represents a specific transpilation of the model. So, if you have made changes to your machine learning model and transpiled it again, it will create a new version. - -This system of models and versions allows you to manage and keep track of the evolution of your machine learning models over time. - -For example, let's say you have created a model called `awesome_model` and transpiled it twice. This will create two versions of the model, version 1 and version 2. You can check the status of these versions using the `giza versions list --model-id ...` command. - -```console -giza versions list --model-id 29 -[giza][2023-09-13 14:17:08.006] Listing versions for the model βœ… -[ - { - "version": 1, - "size": 52735, - "status": "COMPLETED", - "message": "Transpilation Successful!", - "description": "Initial version", - "created_date": "2023-09-13T12:08:38.177605", - "last_update": "2023-09-13T12:08:43.986137" - }, - { - "version": 2, - "size": 52735, - "status": "COMPLETED", - "message": "Transpilation Successful!", - "description": "Initial version", - "created_date": "2023-09-13T12:11:30.165440", - "last_update": "2023-09-13T12:11:31.625834" - } -] -``` diff --git a/docs/frameworks/cairo/verify.md b/docs/frameworks/cairo/verify.md deleted file mode 100644 index eb7f368..0000000 --- a/docs/frameworks/cairo/verify.md +++ /dev/null @@ -1,41 +0,0 @@ -# Verify - -After successfully creating a proof for your Orion Cairo model, the next step is to verify its validity. Giza offers two methods for proof verification: using the `proof-id` or directly specifying the proof file path. - -## Option 1: Verify Using Proof-ID - -To verify a proof by providing the `proof-id`, use the following command: - -``` -giza verify --model-id 1 --version-id 1 --proof-id 1 --size S -``` - -Upon successful submission, you will see a confirmation message indicating that the verification procces has begun. Once the verification process is complete, a success message will confirm the validity of the proof: - -``` -[giza][2024-04-22 13:48:12.236] Verifying proof... -[giza][2024-04-22 13:48:14.985] Verification result: True -[giza][2024-04-22 13:48:14.985] Verification time: 2.363822541 -``` - -A `--use-remote` flag can be added to the command to verify the proof using a job. This flag is optional and its strongly discouraged as verification time is 10x slower than the default method. -``` - -## Option 2: Verify by Providing the Proof Path - -Alternatively, you can verify a proof by specifying the path to the proof file directly. This option uses by default the `--use-job` flag to verify the proof using a job. To verify a proof using the proof file path, use the following command: - -``` -giza verify --proof /path/to/the/proof --size S -``` - -Similar to the first option, you will receive confirmation of the verification job creation followed by a success message upon completion: - -``` -[giza][2023-12-04 19:43:37.686] Verification job created with name 'verify-cairo-20231204-32f44715' and id -> 1 βœ… -[giza][2023-12-04 19:45:18.683] Verification job is successful βœ… -``` - -## Verification Outcome - -If the verification job completes successfully, it indicates that the proof is valid. If there are any issues during the verification process, Giza will provide an error message detailing the problem. diff --git a/docs/frameworks/ezkl/README.md b/docs/frameworks/ezkl/README.md deleted file mode 100644 index 6f9219e..0000000 --- a/docs/frameworks/ezkl/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# EZKL - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -`ezkl` is a library and command-line tool for doing inference for deep learning models and other computational graphs in a zk-snark (ZKML) using `halo2` as a backend. [Official documentation](https://docs.ezkl.xyz/). - -`ezkl` represents a pioneering framework in zero-knowledge machine learning (ZKML) trusted by Giza. It is designed with ease of use in mind and efficiency to make easy zero-knowledge inference. - -## EZKL Framework Features - -1. Transpilation Process - -The transpilation process refers to performing the `setup` for the model where an ONNX model and a set of input data are used to generate the `circuit settings`, `proving key` and `verification key` files that are used to perform the inference. In Giza we aim to provide an easy way to perform this step providing compute resources and a simple command line interface. More on this in the [transpile documentation for ezkl](transpile.md). - -1. Creating Verifiable Proofs - -Create a proof using the generated outputs of the setup process, we handle this step for you by loading the necessary files and performing the proof generation for you. More on this in the [prove documentation for ezkl](prove.md). - -1. Verifying Proofs - -Verify the proof generated by an `ezkl` version, here we manage the execution of the verification process and the compute as well for you. More on this in the [verify documentation for ezkl](verify.md) - -For detailed information check the [ezkl repository](https://github.com/zkonduit/ezkl) diff --git a/docs/frameworks/ezkl/deploy.md b/docs/frameworks/ezkl/deploy.md deleted file mode 100644 index a9e5779..0000000 --- a/docs/frameworks/ezkl/deploy.md +++ /dev/null @@ -1,149 +0,0 @@ -# Deploy - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -To deploy a model, you must first have a version of that model. If you have not yet created a version, please refer to the [versions](../../resources/versions.md) documentation. - -To create a new service, users can employ the `deploy` command. This command facilitates the deployment of a machine learning service ready to accept predictions at the `/predict` endpoint, providing a straightforward method for deploying and using machine learning capabilities as an API endpoint. As we are using `EZKL` we need to add `--framework EZKL` (or `-f EZKL` for short) to the command: - -{% code overflow="wrap" %} -```shell -> giza endpoints deploy --model-id 1 --version-id 1 --framework EZKL -β–°β–°β–°β–°β–°β–±β–± Creating endpoint! -[giza][2024-02-07 12:31:02.498] Endpoint is successful βœ… -[giza][2024-02-07 12:31:02.501] Endpoint created with id -> 1 βœ… -[giza][2024-02-07 12:31:02.502] Endpoint created with endpoint URL: https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app πŸŽ‰ -``` -{% endcode %} - -## Example Request - -Now the model is available to generate predictions and generate proofs of those predictions. The schema of the data is the same as used to create the `input.json` needed to create version, for a linear regression it would be: - -```json -{ - "input_data": [ - [ - 0.12177091836929321, - 0.7048522233963013 - ] - ] -} -``` - -To execute a prediction using **cURL**: - -```sh -curl https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app/predict \ --H "Content-Type: application/json" -d '{ - "input_data": [ - [ - 0.12177091836929321, - 0.7048522233963013 - ] - ] -}' | jq -``` - -This yields the following response: - -```json -{ - "prediction": [ - [ - 4.53125 - ] - ], - "request_id": "d0564505755944b8bef9292d980f3e27" -} -``` - -There is an extra args, `job_size`, that can be used in each request to specify the size of the proving job so it has more CPU and memory available to generate the proof. An example: - -```sh -curl https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app/predict \ --H "Content-Type: application/json" -d '{ - "input_data": [ - [ - 0.12177091836929321, - 0.7048522233963013 - ] - ], - "job_size": "M" -}' | jq -``` - -Available sizes are `S`, `M`, `L,` and `XL`, each with different usage limits. - -## List the proving jobs for an endpoint - -To list the proving jobs for an endpoint, we can use the `list-jobs` command available for the endpoints. This command will return a list of all the proving jobs for the endpoint with the `request_id` for easier tracking. - -```console -giza endpoints list-jobs --endpoint-id 1 -[giza][2024-03-06 18:13:50.485] Getting jobs from endpoint 1 βœ… -[ - { - "id": 1, - "job_name": "proof-ezkl-20240306-979342e7", - "size": "S", - "status": "Completed", - "elapsed_time": 120., - "created_date": "2024-03-06T16:12:31.295958", - "last_update": "2024-03-06T16:14:29.952678", - "request_id": "979342e7b94641f0a260c1997d9ccfee" - }, - { - "id": 2, - "job_name": "proof-ezkl-20240306-f6559749", - "size": "S", - "status": "COMPLETED", - "elapsed_time": 120.0, - "created_date": "2024-03-06T16:43:27.531250", - "last_update": "2024-03-06T16:45:17.272684", - "request_id": "f655974900d8479c9bb662a060bc1365" - } -] -``` - -## List the proofs for an endpoint - -To list the proofs for an endpoint, we can use the `list-proofs` command available for the endpoints. This command will return a list of all the proofs for the endpoint with the `request_id` for easier tracking. - -```console -giza endpoints list-proofs --endpoint-id 1 -[giza][2024-03-06 18:15:23.146] Getting proofs from endpoint 1 βœ… -[ - { - "id": 1, - "job_id": 1, - "metrics": { - "proving_time": 0.03023695945739746 - }, - "created_date": "2024-03-06T16:44:46.196186", - "request_id": "979342e7b94641f0a260c1997d9ccfee" - }, - { - "id": 1, - "job_id": 2, - "metrics": { - "proving_time": 0.07637895945739746 - }, - "created_date": "2024-03-06T16:44:46.196186", - "request_id": "f655974900d8479c9bb662a060bc1365" - } -] -``` - -## Download the proof - -We can download the proof using the `download-proof` command available for the endpoints: - -
❯ giza endpoints download-proof --proof-id "d0564505755944b8bef9292d980f3e27"
-[giza][2024-02-20 15:40:48.560] Getting proof from endpoint 1 βœ…
-[giza][2024-02-20 15:40:49.288] Proof downloaded to zk.proof βœ…
-
- -The `proof id` used is the `request_id` returned in the response. diff --git a/docs/frameworks/ezkl/prove.md b/docs/frameworks/ezkl/prove.md deleted file mode 100644 index cef567a..0000000 --- a/docs/frameworks/ezkl/prove.md +++ /dev/null @@ -1,26 +0,0 @@ -# Prove - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -Time to create a Proof of our EZKL version! - -Once we have the input data that we want to use we can use the `prove` command to create our proof! - -This command will create a proving job at Giza and once the job is completed we will download the created proof. - -```console -> giza prove --framework EZKL --model-id 1 --version-id 1 --size M input.json -[giza][2023-12-04 19:41:55.236] Proving job created with name 'proof-ezkl-20231204-33e59441' and id -> 1 βœ… -[giza][2023-12-04 19:43:36.337] Proving job is successful βœ…[giza][2023-12-04 19:43:36.447] Proof created with id -> 1 βœ… -[giza][2023-12-04 19:43:36.448] Proof metrics: -{ - "proving_time": 12.2238187789917 -} -[giza][2023-12-04 19:43:37.046] Proof saved at: zk.proof -``` - -As we can see the job takes some time, and because of this we are actively waiting for the job to be completed, once it's done all information and the proof are retrieved. - -Now we can see that we have a proof successfully created! Now if we want we could verify it! Let's check the [verify](../frameworks/ezkl/verify.md) documentation to see how to do it! diff --git a/docs/frameworks/ezkl/transpile.md b/docs/frameworks/ezkl/transpile.md deleted file mode 100644 index 4f1f9f1..0000000 --- a/docs/frameworks/ezkl/transpile.md +++ /dev/null @@ -1,117 +0,0 @@ -# Transpile - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -Transpilation is a crucial process in the deployment of Verifiable Machine Learning models and its powered by is powered by [ezkl](https://github.com/zkonduit/ezkl). It involves the usage of an ONNX model and input data to perform the `setup`. With this `setup` we can generate proofs that can be verified, ensuring the integrity and reliability of the model's predictions. - -The transpilation process begins by reading the model and input data from the specified path. The model and data are then sent for transpilation. By default, the output of this process is managed by Giza for later use. - -```console -> giza transpile --framework EZKL --input-data input.json awesome_model.onnx -[giza][2023-12-04 19:40:11.274] No model id provided, checking if model exists βœ… -[giza][2023-12-04 19:40:11.275] Model name is: awesome_model -[giza][2023-12-04 19:40:11.424] Model Created with id -> 1! βœ… -[giza][2023-12-04 19:40:11.944] Sending model for setup βœ… -[giza][2023-12-04 19:40:13.046] Setup job created with name 'ezkl-job-20231204-32a4a1c1' and id -> 1 βœ… -[giza][2023-12-04 19:41:54.277] Setup job is successful βœ… -``` - -The result of the transpilation process is the following: - -* Circuit settings -* Proving key -* Verification key - -## How do we transpile a model - -There are three main methods for transpiling a model: - -### **Method 1: Using the `giza transpile --framework EZKL` command** - -* This is the simplest method and is recommended for most users. -* When you run this command, Giza handles everything for you. -* It first checks if a model with the specified name already exists. If not, it creates a new model and then transpiles it. -* The output of this process is managed by Giza. -* This is the strategy that we followed in the example before. - -### **Method 2: Manually creating a model and then transpiling it** - -* This method gives you more control over the process. -* First, you create a model manually using the `giza models create` command. -* After the model is created, you can transpile it using the `giza transpile --framework EZKL --model-id ...` or `giza versions transpile --framework EZKL --model-id` command. -* This method is useful when you want to specify particular options or parameters during the model creation and transpilation process. - -```console -> giza models create --name awesome_model --description "A Model for testing different models" -[giza][2023-09-13 14:04:59.532] Creating model βœ… -{ - "id": 2, - "name": "awesome_model", - "description": "A Model for testing different models" -} -``` - -```console -> giza transpile --framework EZKL --model-id 2 --input-data input.json awesome_model.onnx -[giza][2023-12-04 19:40:10.646] Model found with id -> 2! βœ… -[giza][2023-12-04 19:40:12.176] Sending model for Setup βœ… -[giza][2023-12-04 19:40:13.046] Setup job created with name 'ezkl-job-20231204-32a4a1c1' and id -> 13 βœ… -[giza][2023-12-04 19:41:54.277] Setup job is successful βœ… -``` - -### **Method 3: Using a previous model** - -* If you have a previously created model, you can transpile it by indicating the model-id in the `giza transpile --framework EZKL --model-id ...` or `giza versions transpile --framework EZKL --model-id` command. -* This method is useful when you want to create a new version of an existing model. -* The output of the transpilation process is saved in the same location as the original model. - -```console -# Using the previous model (id: 2) we can transpile a new model, which will create version 2 of the model. -> giza transpile --framework EZKL --model-id 2 --input-data input.json awesome_model.onnx -[giza][2023-12-04 19:40:10.646] Model found with id -> 2! βœ… -[giza][2023-12-04 19:40:12.176] Sending model for Setup βœ… -[giza][2023-12-04 19:40:13.046] Setup job created with name 'ezkl-job-20231204-123fadc1' and id -> 14 βœ… -[giza][2023-12-04 19:41:54.277] Setup job is successful βœ… -``` - -## What is happening with the models and versions - -In Giza, a model is essentially a container for versions. Each version represents a transpilation of a machine learning model at a specific point in time. This allows you to keep track of different versions of your model as it evolves and improves over time. - -To check the current models and versions that have been created, you can use the following steps: - -1. Use the `giza models list` command to list all the models that have been created. -2. For each model, you can use the `giza versions list --model-id ...` command to list all the versions of that model. - -Remember, each version represents a specific transpilation of the model. So, if you have made changes to your machine learning model and transpiled it again, it will create a new version. - -This system of models and versions allows you to manage and keep track of the evolution of your machine learning models over time. - -For example, let's say you have created a model called `awesome_model` and transpiled it twice. This will create two versions of the model, version 1 and version 2. You can check the status of these versions using the `giza versions list --model-id ...` command. - -```console -giza versions list --model-id 29 -[giza][2023-12-04 14:17:08.006] Listing versions for the model βœ… -[ - { - "version": 1, - "size": 52735, - "status": "COMPLETED", - "message": "Setup Successful!", - "description": "Initial version", - "created_date": "2023-09-13T12:08:38.177605", - "last_update": "2023-09-13T12:08:43.986137" - }, - { - "version": 2, - "size": 52735, - "status": "Setup", - "message": "Transpilation Successful!", - "description": "Initial version", - "created_date": "2023-12-04T12:11:30.165440", - "last_update": "2023-12-04T12:11:31.625834" - } -] -``` diff --git a/docs/frameworks/ezkl/verify.md b/docs/frameworks/ezkl/verify.md deleted file mode 100644 index c93961c..0000000 --- a/docs/frameworks/ezkl/verify.md +++ /dev/null @@ -1,19 +0,0 @@ -# Verify - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -We have created a Proof of our EZKL version, now it's time to verify it! - -As we already have the proof we can use the `verify` command to verify it, using the `--proof-id` option we can specify the proof that we want to verify. - -As we are using a managed `version` we need to specify `--model-id` and `--version-id` to indicate which version we want to verify, so we can retrieve the generated files in the `setup` process (`giza transpile`). - -```console -> giza verify -f EZKL --model-id 1 --version-id 1 --proof-id 1 --size S -[giza][2023-12-04 19:43:37.686] Verification job created with name 'verify-ezkl-20231204-32f44715' and id -> 1 βœ… -[giza][2023-12-04 19:45:18.683] Verification job is successful βœ… -``` - -If the job is successful that means that the proof is valid! Otherwise, we will get an error message. diff --git a/docs/reference/api/README.md b/docs/reference/api/README.md deleted file mode 100644 index 3492011..0000000 --- a/docs/reference/api/README.md +++ /dev/null @@ -1,120 +0,0 @@ - - -# API Overview - -## Modules - -- [`callbacks`](./callbacks.md#module-callbacks) -- [`cli`](./cli.md#module-cli) -- [`client`](./client.md#module-client) -- [`commands`](./commands.md#module-commands) -- [`commands.actions`](./commands.actions.md#module-commandsactions) -- [`commands.agents`](./commands.agents.md#module-commandsagents) -- [`commands.endpoints`](./commands.endpoints.md#module-commandsendpoints) -- [`commands.models`](./commands.models.md#module-commandsmodels) -- [`commands.prove`](./commands.prove.md#module-commandsprove) -- [`commands.reset_password`](./commands.reset_password.md#module-commandsreset_password) -- [`commands.users`](./commands.users.md#module-commandsusers) -- [`commands.verify`](./commands.verify.md#module-commandsverify) -- [`commands.version`](./commands.version.md#module-commandsversion) -- [`commands.versions`](./commands.versions.md#module-commandsversions) -- [`commands.workspaces`](./commands.workspaces.md#module-commandsworkspaces) -- [`exceptions`](./exceptions.md#module-exceptions) -- [`frameworks`](./frameworks.md#module-frameworks) -- [`frameworks.cairo`](./frameworks.cairo.md#module-frameworkscairo) -- [`frameworks.ezkl`](./frameworks.ezkl.md#module-frameworksezkl) -- [`options`](./options.md#module-options) -- [`utils`](./utils.md#module-utils) -- [`utils.decorators`](./utils.decorators.md#module-utilsdecorators) -- [`utils.echo`](./utils.echo.md#module-utilsecho) -- [`utils.enums`](./utils.enums.md#module-utilsenums) -- [`utils.exception_handling`](./utils.exception_handling.md#module-utilsexception_handling) -- [`utils.misc`](./utils.misc.md#module-utilsmisc) - -## Classes - -- [`client.AgentsClient`](./client.md#class-agentsclient): Client to interact with `agents` endpoint. -- [`client.ApiClient`](./client.md#class-apiclient): Implementation of the API client to interact with core-services -- [`client.EndpointsClient`](./client.md#class-endpointsclient): Client to interact with `endpoints` endpoint. -- [`client.EndpointsClient`](./client.md#class-endpointsclient): Client to interact with `endpoints` endpoint. -- [`client.JobsClient`](./client.md#class-jobsclient): Client to interact with `jobs` endpoint. -- [`client.ModelsClient`](./client.md#class-modelsclient): Client to interact with `models` endpoint. -- [`client.ProofsClient`](./client.md#class-proofsclient): Client to interact with `proofs` endpoint. -- [`client.TranspileClient`](./client.md#class-transpileclient): Client to interact with `users` endpoint. -- [`client.UsersClient`](./client.md#class-usersclient): Client to interact with `users` endpoint. -- [`client.VersionJobsClient`](./client.md#class-versionjobsclient): Client to interact with `jobs` endpoint. -- [`client.VersionsClient`](./client.md#class-versionsclient): Client to interact with `versions` endpoint. -- [`client.WorkspaceClient`](./client.md#class-workspaceclient): Client to interact with `workspaces` endpoint. -- [`exceptions.PasswordError`](./exceptions.md#class-passworderror) -- [`exceptions.ScarbBuildError`](./exceptions.md#class-scarbbuilderror) -- [`exceptions.ScarbNotFound`](./exceptions.md#class-scarbnotfound) -- [`echo.Echo`](./utils.echo.md#class-echo): Helper class to use when printin output of the CLI. -- [`enums.Framework`](./utils.enums.md#class-framework) -- [`enums.JobKind`](./utils.enums.md#class-jobkind) -- [`enums.JobSize`](./utils.enums.md#class-jobsize) -- [`enums.JobStatus`](./utils.enums.md#class-jobstatus) -- [`enums.ServiceSize`](./utils.enums.md#class-servicesize) -- [`enums.VersionStatus`](./utils.enums.md#class-versionstatus) -- [`exception_handling.ExceptionHandler`](./utils.exception_handling.md#class-exceptionhandler): Context manager to handle exceptions in the CLI. - -## Functions - -- [`callbacks.debug_callback`](./callbacks.md#function-debug_callback): If a call adds the `--debug` flag debugging mode is activated for external requests and API Clients. -- [`callbacks.version_callback`](./callbacks.md#function-version_callback): Prints the current version when `--version` flag is added to a call. -- [`cli.entrypoint`](./cli.md#function-entrypoint) -- [`actions.new`](./commands.actions.md#function-new): This command will create a new action by generating a Python project. -- [`agents.create`](./commands.agents.md#function-create) -- [`agents.delete_agent`](./commands.agents.md#function-delete_agent) -- [`agents.get`](./commands.agents.md#function-get) -- [`agents.list`](./commands.agents.md#function-list) -- [`agents.update`](./commands.agents.md#function-update) -- [`endpoints.delete_endpoint`](./commands.endpoints.md#function-delete_endpoint) -- [`endpoints.deploy`](./commands.endpoints.md#function-deploy) -- [`endpoints.download_proof`](./commands.endpoints.md#function-download_proof) -- [`endpoints.get`](./commands.endpoints.md#function-get) -- [`endpoints.get_proof`](./commands.endpoints.md#function-get_proof) -- [`endpoints.list`](./commands.endpoints.md#function-list) -- [`endpoints.list_jobs`](./commands.endpoints.md#function-list_jobs) -- [`endpoints.list_proofs`](./commands.endpoints.md#function-list_proofs) -- [`endpoints.verify`](./commands.endpoints.md#function-verify) -- [`models.create`](./commands.models.md#function-create): Command to create a model. Asks for the new model's information and validates the input, -- [`models.get`](./commands.models.md#function-get): Command to create a user. Asks for the new users information and validates the input, -- [`models.list`](./commands.models.md#function-list): Command to list all models. -- [`prove.prove`](./commands.prove.md#function-prove) -- [`reset_password.handle_http_error`](./commands.reset_password.md#function-handle_http_error): Handle an HTTP error. -- [`reset_password.prompt_for_input`](./commands.reset_password.md#function-prompt_for_input): Prompt the user for input. -- [`reset_password.request_reset_password_token`](./commands.reset_password.md#function-request_reset_password_token): Request a password reset token for a given email. -- [`reset_password.reset_password`](./commands.reset_password.md#function-reset_password): Reset the password for a user using a reset token. -- [`users.create`](./commands.users.md#function-create): Command to create a user. Asks for the new users information and validates the input, -- [`users.create_api_key`](./commands.users.md#function-create_api_key): Create an API key for your user. You need to be logged in to create an API key. -- [`users.login`](./commands.users.md#function-login): Logs the current user into Giza. Under the hood this will retrieve the token for the next requests. -- [`users.me`](./commands.users.md#function-me): Retrieve information about the current user and print it as json to stdout. -- [`users.resend_email`](./commands.users.md#function-resend_email): Command to resend verification email. Asks for the user's email and sends the request to the API -- [`verify.verify`](./commands.verify.md#function-verify) -- [`version.check_version`](./commands.version.md#function-check_version): Check if there is a new version available of the cli in pypi to suggest upgrade -- [`versions.download`](./commands.versions.md#function-download): Retrieve information about the current user and print it as json to stdout. -- [`versions.download_original`](./commands.versions.md#function-download_original): Retrieve information about the current user and print it as json to stdout. -- [`versions.get`](./commands.versions.md#function-get) -- [`versions.list`](./commands.versions.md#function-list) -- [`versions.transpile`](./commands.versions.md#function-transpile) -- [`versions.update`](./commands.versions.md#function-update) -- [`versions.update_sierra`](./commands.versions.md#function-update_sierra) -- [`workspaces.create`](./commands.workspaces.md#function-create): Command to create a Giza Workspace. -- [`workspaces.delete`](./commands.workspaces.md#function-delete) -- [`workspaces.get`](./commands.workspaces.md#function-get) -- [`cairo.deploy`](./frameworks.cairo.md#function-deploy): Command to deploy a specific version of a model. This will create an endpoint for the specified version and check the status, once it finishes if COMPLETED the endpoint is ready to be used. -- [`cairo.prove`](./frameworks.cairo.md#function-prove): Command to prove as spceific cairo program, previously converted to CASM. -- [`cairo.transpile`](./frameworks.cairo.md#function-transpile): This function is responsible for transpiling a model. The overall objective is to prepare a model for use by converting it into a different format (transpiling). -- [`cairo.verify`](./frameworks.cairo.md#function-verify): Create a verification job. -- [`ezkl.deploy`](./frameworks.ezkl.md#function-deploy): Command to deploy a specific version of a model. This will create a endpoint for the specified version and check the status, once it finishes if COMPLETED the endpoint is ready to be used. -- [`ezkl.prove`](./frameworks.ezkl.md#function-prove) -- [`ezkl.setup`](./frameworks.ezkl.md#function-setup): This function executes the setup of the model and creates the outputs, handled by Giza. -- [`ezkl.verify`](./frameworks.ezkl.md#function-verify): Create a verification job. -- [`utils.get_response_info`](./utils.md#function-get_response_info): Utility to retrieve information of the client response. -- [`decorators.auth`](./utils.decorators.md#function-auth): Check that we have the token and it is not expired before executing -- [`misc.download_model_or_sierra`](./utils.misc.md#function-download_model_or_sierra): Download the model or sierra file. -- [`misc.get_ape_accounts`](./utils.misc.md#function-get_ape_accounts): Get the available APE accounts. -- [`misc.get_parameters_from_str`](./utils.misc.md#function-get_parameters_from_str): Get the parameters from a string. -- [`misc.load_json_file`](./utils.misc.md#function-load_json_file): Load a json file. -- [`misc.scarb_build`](./utils.misc.md#function-scarb_build): Build the scarb model. -- [`misc.zip_folder`](./utils.misc.md#function-zip_folder): Zip the folder to a specific location. diff --git a/docs/reference/api/callbacks.md b/docs/reference/api/callbacks.md deleted file mode 100644 index 6460f65..0000000 --- a/docs/reference/api/callbacks.md +++ /dev/null @@ -1,61 +0,0 @@ - - - - -# module `callbacks` - - - - - ---- - - - -## function `version_callback` - -```python -version_callback(value: bool) β†’ None -``` - -Prints the current version when `--version` flag is added to a call. - - - -**Args:** - - - `value` (bool): represents if the flag has been added or not to the call. - - - -**Raises:** - - - `Exit`: exit the CLI execution - - ---- - - - -## function `debug_callback` - -```python -debug_callback(_, value: bool) -``` - -If a call adds the `--debug` flag debugging mode is activated for external requests and API Clients. - - - -**Args:** - - - `_` (_type_): discarded value - - `value` (bool): represents if the flag has been added to the call or not - - - -**Returns:** - - - `bool`: pass the value back so it can be used in the clients - - diff --git a/docs/reference/api/cli.md b/docs/reference/api/cli.md deleted file mode 100644 index 0d692ce..0000000 --- a/docs/reference/api/cli.md +++ /dev/null @@ -1,28 +0,0 @@ - - - - -# module `cli` - - - - -**Global Variables** ---------------- -- **click** - ---- - - - -## function `entrypoint` - -```python -entrypoint() -``` - - - - - - diff --git a/docs/reference/api/client.md b/docs/reference/api/client.md deleted file mode 100644 index 4ac99f4..0000000 --- a/docs/reference/api/client.md +++ /dev/null @@ -1,2317 +0,0 @@ - - - - -# module `client` - - - - -**Global Variables** ---------------- -- **DEFAULT_API_VERSION** -- **GIZA_TOKEN_VARIABLE** -- **MODEL_URL_HEADER** -- **API_KEY_HEADER** - - ---- - - - -## class `ApiClient` -Implementation of the API client to interact with core-services - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - - ---- - - - -## class `UsersClient` -Client to interact with `users` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create(user: UserCreate) β†’ UserResponse -``` - -Call the API to create a new user - - - -**Args:** - - - `user` (users.UserCreate): information used to create a new user - - - -**Returns:** - - - `users.UserResponse`: the created user information - ---- - - - -### method `create_api_key` - -```python -create_api_key() -``` - -Call the API to create a new API key - - - -**Returns:** - - - `users.UserResponse`: the created user information - ---- - - - -### method `me` - -```python -me() β†’ UserResponse -``` - -Retrieve information about the current user. Must have a valid token to perform the operation, enforced by `@auth` - - - -**Returns:** - - - `users.UserResponse`: User information from the server - ---- - - - -### method `request_reset_password_token` - -```python -request_reset_password_token(email: str) β†’ Msg -``` - -Sends a request to the server to generate a password reset token. The token is sent to the user's email. - - - -**Args:** - - - `email` (str): The email of the user who wants to reset their password. - - - -**Returns:** - - - `Msg`: A message indicating the success or failure of the request. - ---- - - - -### method `resend_email` - -```python -resend_email(email: str) β†’ Msg -``` - -Resend the verification email to the user. - - - -**Args:** - - - `email` (EmailStr): The email of the user who wants to resend the verification email. - - - -**Returns:** - - - `Msg`: A message indicating the success or failure of the request. - ---- - - - -### method `reset_password` - -```python -reset_password(token: str, new_password: str) β†’ Msg -``` - -Resets the user's password using the provided token and new password. - - - -**Args:** - - - `token` (str): The password reset token sent to the user's email. - - `new_password` (str): The new password the user wants to set. - - - -**Returns:** - - - `Msg`: A message indicating the success or failure of the password reset. - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - - ---- - - - -## class `EndpointsClient` -Client to interact with `endpoints` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create( - model_id: int, - version_id: int, - endpoint_create: EndpointCreate, - f: Optional[BufferedReader] = None -) β†’ Endpoint -``` - -Create a new deployment. - - - -**Args:** - - - `endpoint_create`: Endpoint information to create - - - -**Returns:** - The recently created deployment information - ---- - - - -### method `delete` - -```python -delete(endpoint_id: int) β†’ None -``` - -Delete an endpoint. - - - -**Args:** - - - `endpoint_id`: Endpoint identifier - ---- - - - -### method `download_proof` - -```python -download_proof(endpoint_id: int, proof_id: Union[int, str]) β†’ bytes -``` - -Download a proof. - - - -**Args:** - - - `proof_id`: Proof identifier - - - -**Returns:** - The proof binary file - ---- - - - -### method `get` - -```python -get(endpoint_id: int) β†’ Endpoint -``` - -Get a deployment. - - - -**Args:** - - - `endpoint_id`: Endpoint identifier - - - -**Returns:** - The deployment information - ---- - - - -### method `get_proof` - -```python -get_proof(endpoint_id: int, proof_id: Union[int, str]) β†’ Proof -``` - -Return information about a specific proof. `proof_if` is the identifier of the proof that can be a integer or the request id. - - - -**Returns:** - A proof created by the user - ---- - - - -### method `list` - -```python -list(params: Optional[Dict[str, Any]] = None) β†’ EndpointsList -``` - -List endpoints. - - - -**Returns:** - A list of endpoints created by the user - ---- - - - -### method `list_jobs` - -```python -list_jobs(endpoint_id: int) β†’ JobList -``` - -List proofs. - - - -**Returns:** - A list of proofs created by the user - ---- - - - -### method `list_proofs` - -```python -list_proofs(endpoint_id: int) β†’ ProofList -``` - -List proofs. - - - -**Returns:** - A list of proofs created by the user - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - ---- - - - -### method `verify_proof` - -```python -verify_proof(endpoint_id: int, proof_id: Union[str, int]) β†’ VerifyResponse -``` - -Verify a proof. - - - -**Args:** - - - `endpoint_id`: Endpoint identifier - - `proof_id`: Proof identifier - - - -**Returns:** - The verification response - - ---- - - - -## class `EndpointsClient` -Client to interact with `endpoints` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create( - model_id: int, - version_id: int, - endpoint_create: EndpointCreate, - f: Optional[BufferedReader] = None -) β†’ Endpoint -``` - -Create a new deployment. - - - -**Args:** - - - `endpoint_create`: Endpoint information to create - - - -**Returns:** - The recently created deployment information - ---- - - - -### method `delete` - -```python -delete(endpoint_id: int) β†’ None -``` - -Delete an endpoint. - - - -**Args:** - - - `endpoint_id`: Endpoint identifier - ---- - - - -### method `download_proof` - -```python -download_proof(endpoint_id: int, proof_id: Union[int, str]) β†’ bytes -``` - -Download a proof. - - - -**Args:** - - - `proof_id`: Proof identifier - - - -**Returns:** - The proof binary file - ---- - - - -### method `get` - -```python -get(endpoint_id: int) β†’ Endpoint -``` - -Get a deployment. - - - -**Args:** - - - `endpoint_id`: Endpoint identifier - - - -**Returns:** - The deployment information - ---- - - - -### method `get_proof` - -```python -get_proof(endpoint_id: int, proof_id: Union[int, str]) β†’ Proof -``` - -Return information about a specific proof. `proof_if` is the identifier of the proof that can be a integer or the request id. - - - -**Returns:** - A proof created by the user - ---- - - - -### method `list` - -```python -list(params: Optional[Dict[str, Any]] = None) β†’ EndpointsList -``` - -List endpoints. - - - -**Returns:** - A list of endpoints created by the user - ---- - - - -### method `list_jobs` - -```python -list_jobs(endpoint_id: int) β†’ JobList -``` - -List proofs. - - - -**Returns:** - A list of proofs created by the user - ---- - - - -### method `list_proofs` - -```python -list_proofs(endpoint_id: int) β†’ ProofList -``` - -List proofs. - - - -**Returns:** - A list of proofs created by the user - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - ---- - - - -### method `verify_proof` - -```python -verify_proof(endpoint_id: int, proof_id: Union[str, int]) β†’ VerifyResponse -``` - -Verify a proof. - - - -**Args:** - - - `endpoint_id`: Endpoint identifier - - `proof_id`: Proof identifier - - - -**Returns:** - The verification response - - ---- - - - -## class `TranspileClient` -Client to interact with `users` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - ---- - - - -### method `transpile` - -```python -transpile(f: ) β†’ Response -``` - -Make a call to the API transpile endpoint with the model as a file. - - - -**Args:** - - - `f` (BinaryIO): model to send for transpilation - - - -**Returns:** - - - `Response`: raw response from the server with the transpiled model as a zip - ---- - - - -### method `update_transpilation` - -```python -update_transpilation( - model_id: int, - version_id: int, - f: -) β†’ None -``` - -Make a call to the API transpile endpoint with the model as a file. - - - -**Args:** - - - `f` (BinaryIO): model to send for transpilation - - - -**Returns:** - - - `Response`: raw response from the server with the transpiled model as a zip - - ---- - - - -## class `ModelsClient` -Client to interact with `models` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create(model_create: ModelCreate) β†’ Model -``` - -Create a new model. - - - -**Args:** - - - `model_create`: Model information to create - - - -**Raises:** - - - `Exception`: if there is no upload Url - - - -**Returns:** - - - `Tuple[Model, str]`: the recently created model and a url, used to upload the model. - ---- - - - -### method `get` - -```python -get(model_id: int, **kwargs) β†’ Model -``` - -Make a call to the API to retrieve model information. - - - -**Args:** - - - `model_id`: Model identfier to retrieve information - - - -**Returns:** - - - `Model`: model entity with the retrieved information - ---- - - - -### method `get_by_name` - -```python -get_by_name(model_name: str, **kwargs) β†’ Optional[Model] -``` - -Make a call to the API to retrieve model information by its name. - - - -**Args:** - - - `model_name`: Model name to retrieve information - - - -**Returns:** - - - `Model`: model entity with the retrieved information - ---- - - - -### method `list` - -```python -list(**kwargs) β†’ ModelList -``` - -List all the models related to the user. - - - -**Returns:** - A list of models created by the user - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - ---- - - - -### method `update` - -```python -update(model_id: int, model_update: ModelUpdate) β†’ Model -``` - -Update a model. - - - -**Args:** - - - `model_id`: Model identfier to retrieve information - - `model_update`: body to partially update the model - - - -**Returns:** - - - `Model`: the updated model - - ---- - - - -## class `JobsClient` -Client to interact with `jobs` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create( - job_create: JobCreate, - trace: Optional[BufferedReader, TextIOWrapper] = None, - memory: Optional[BufferedReader, TextIOWrapper] = None -) β†’ Job -``` - -Create a new job. - - - -**Args:** - - - `job_create`: Job information to create - - `f`: filed to upload, a CASM json - - - -**Raises:** - - - `Exception`: if there is no upload Url - - - -**Returns:** - - - `Tuple[Model, str]`: the recently created model and a url, used to upload the model. - ---- - - - -### method `get` - -```python -get(job_id: int, params: Optional[dict[str, str]] = None) β†’ Job -``` - -Make a call to the API to retrieve job information. - - - -**Args:** - - - `job_id`: Job identfier to retrieve information - - - -**Returns:** - - - `Job`: job entity with the retrieved information - ---- - - - -### method `list` - -```python -list() β†’ List[Job] -``` - -List jobs. - - - -**Returns:** - A list of jobs created by the user - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - - ---- - - - -## class `VersionJobsClient` -Client to interact with `jobs` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create( - model_id: int, - version_id: int, - job_create: JobCreate, - f: TextIOWrapper -) β†’ Job -``` - -Create a new job. - - - -**Args:** - - - `job_create`: Job information to create - - `f`: filed to upload, a CASM json - - - -**Raises:** - - - `Exception`: if there is no upload Url - - - -**Returns:** - - - `Tuple[Model, str]`: the recently created model and a url, used to upload the model. - ---- - - - -### method `get` - -```python -get(model_id: int, version_id: int, job_id: int) β†’ Job -``` - -Make a call to the API to retrieve job information. - - - -**Args:** - - - `job_id`: Job identfier to retrieve information - - - -**Returns:** - - - `Job`: job entity with the retrieved information - ---- - - - -### method `list` - -```python -list(model_id: int, version_id: int) β†’ List[Job] -``` - -List jobs. - - - -**Returns:** - A list of jobs created by the user - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - - ---- - - - -## class `ProofsClient` -Client to interact with `proofs` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `download` - -```python -download(proof_id: int) β†’ bytes -``` - -Download a proof. - - - -**Args:** - - - `proof_id`: Proof identifier - - - -**Returns:** - The proof binary file - ---- - - - -### method `get` - -```python -get(proof_id: int) β†’ Proof -``` - -Make a call to the API to retrieve proof information. - - - -**Args:** - - - `proof_id`: Proof identfier to retrieve information - - - -**Returns:** - - - `Proof`: proof entity with the desired information - ---- - - - -### method `get_by_job_id` - -```python -get_by_job_id(job_id: int) β†’ Proof -``` - -Make a call to the API to retrieve proof information based on the job id. - - - -**Args:** - - - `job_id`: Job identifier to query by. - - - -**Returns:** - - - `Proof`: proof entity with the desired information - ---- - - - -### method `list` - -```python -list() β†’ List[Proof] -``` - -List all the proofs related to the user. - - - -**Returns:** - A list of proofs created by the user - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - ---- - - - -### method `verify_proof` - -```python -verify_proof(proof_id: int) β†’ VerifyResponse -``` - -Verify a proof. - - - -**Args:** - - - `proof_id`: Proof identifier - - - -**Returns:** - The verification response - - ---- - - - -## class `VersionsClient` -Client to interact with `versions` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create( - model_id: int, - version_create: VersionCreate, - filename: Optional[str] = None -) β†’ Tuple[Version, str] -``` - -Create a new version. - - - -**Args:** - - - `model_id`: Model identifier - - `version_create`: Version information to create - - - -**Returns:** - The recently created version information - ---- - - - -### method `download` - -```python -download(model_id: int, version_id: int, params: Dict) β†’ Dict[str, bytes] -``` - -Download a version. - - - -**Args:** - - - `model_id`: Model identifier - - `version_id`: Version identifier - - `params`: Additional parameters to pass to the request - - - -**Returns:** - The version binary file - ---- - - - -### method `download_original` - -```python -download_original(model_id: int, version_id: int) β†’ bytes -``` - -Download the original version. - - - -**Args:** - - - `model_id`: Model identifier - - `version_id`: Version identifier - - - -**Returns:** - The version binary file - ---- - - - -### method `get` - -```python -get(model_id: int, version_id: int) β†’ Version -``` - -Get a version. - - - -**Args:** - - - `model_id`: Model identifier - - `version_id`: Version identifier - - - -**Returns:** - The version information - ---- - - - -### method `list` - -```python -list(model_id: int) β†’ VersionList -``` - -List all the versions related to a model. - - - -**Args:** - - - `model_id`: Model identifier - - - -**Returns:** - A list of versions related to the model - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - ---- - - - -### method `update` - -```python -update(model_id: int, version_id: int, version_update: VersionUpdate) β†’ Version -``` - -Update a specific version. - - - -**Args:** - - - `model_id`: Model identifier - - `version_id`: Version identifier - - `version_update`: Version information to update - - - -**Returns:** - The updated version information - ---- - - - -### method `upload_cairo` - -```python -upload_cairo(model_id: int, version_id: int, file_path: str) β†’ Version -``` - -Get the Cairo model URL. - - - -**Args:** - - - `model_id`: Model identifier - - `version_id`: Version identifier - - - -**Returns:** - The Cairo model URL - - ---- - - - -## class `WorkspaceClient` -Client to interact with `workspaces` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create() β†’ Workspace -``` - -Call the API to create a new workspace. If the workspace already exists it will return a 400. - - - -**Returns:** - - - `Workspace`: the created workspace information - ---- - - - -### method `delete` - -```python -delete() β†’ None -``` - -Call the API to delete the workspace. If the workspace does not exist it will return a 404. - - - -**Returns:** - None - ---- - - - -### method `get` - -```python -get() β†’ Workspace -``` - -Make a call to the API to retrieve workspace information. Only one should exist. - - - -**Returns:** - - - `Workspace`: workspace information - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - - ---- - - - -## class `AgentsClient` -Client to interact with `agents` endpoint. - - - -### method `__init__` - -```python -__init__( - host: str, - token: Optional[str] = None, - api_key: Optional[str] = None, - api_version: str = 'v1', - verify: bool = True, - debug: Optional[bool] = False -) β†’ None -``` - - - - - - - - ---- - - - -### method `create` - -```python -create(agent_create: AgentCreate) β†’ Agent -``` - -Create a new agent. - - - -**Args:** - - - `agent_create`: Agent information to create - - - -**Returns:** - The recently created agent - ---- - - - -### method `delete` - -```python -delete(agent_id: int) β†’ None -``` - -Delete an agent. - - - -**Args:** - - - `agent_id`: Agent identifier - ---- - - - -### method `get` - -```python -get(agent_id: int, params: Optional[Dict[str, Any]] = None) β†’ Agent -``` - -Get an agent. - - - -**Args:** - - - `agent_id`: Agent identifier - - - -**Returns:** - The agent information - ---- - - - -### method `list` - -```python -list(params: Optional[Dict[str, Any]] = None) β†’ AgentList -``` - -List endpoints. - - - -**Returns:** - A list of endpoints created by the user - ---- - - - -### method `patch` - -```python -patch(agent_id: int, agent_update: AgentUpdate) β†’ Agent -``` - -Update an agent. - - - -**Args:** - - - `agent_id`: Agent identifier - - `agent_update`: Agent information to update - - - -**Returns:** - The updated agent information - ---- - - - -### method `retrieve_api_key` - -```python -retrieve_api_key() β†’ None -``` - -Retrieve the API key from the `~/.giza/.api_key.json` file. - - - -**Raises:** - - - `Exception`: if the file does not exist - - - -**Returns:** - - - `str`: the API key - ---- - - - -### method `retrieve_token` - -```python -retrieve_token( - user: Optional[str] = None, - password: Optional[str] = None, - renew: bool = False -) β†’ None -``` - -Get the JWT token. - -First, it will try to get it from GIZA_TOKEN. Second, from ~/.giza/.credentials.json. And finally it will try to retrieve it from the API login the user in. - - - -**Args:** - - - `user`: if provided it will be used to check against current credentials and if provided with `password` used to retrieve a new token. - - `password`: if provided with `user` it will be used to retrieve a new token. - - `renew`: for renewal of the JWT token by user login. - - - -**Raises:** - - - `Exception`: if token could not be retrieved in any way - - diff --git a/docs/reference/api/commands.deploy.md b/docs/reference/api/commands.deploy.md deleted file mode 100644 index 94c65b9..0000000 --- a/docs/reference/api/commands.deploy.md +++ /dev/null @@ -1,2 +0,0 @@ -# commands.deploy - diff --git a/docs/reference/api/commands.md b/docs/reference/api/commands.md deleted file mode 100644 index 95ba3fa..0000000 --- a/docs/reference/api/commands.md +++ /dev/null @@ -1,11 +0,0 @@ - - - - -# module `commands` - - - - - - diff --git a/docs/reference/api/commands.models.md b/docs/reference/api/commands.models.md deleted file mode 100644 index 015c595..0000000 --- a/docs/reference/api/commands.models.md +++ /dev/null @@ -1,106 +0,0 @@ - - - - -# module `commands.models` - - - - -**Global Variables** ---------------- -- **API_HOST** - ---- - - - -## function `get` - -```python -get( - model_id: int = typer.Option( - ..., "--model-id", "-m", help="Model id to retrieve information from" - ), - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Command to create a user. Asks for the new users information and validates the input, then sends the information to the API - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False). - - - -**Raises:** - - - `ValidationError`: input fields are validated, if these are not suitable the exception is raised - - `HTTPError`: request error to the API, 4XX or 5XX - - ---- - - - -## function `list` - -```python -list( - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Command to list all models. - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False). - - - -**Raises:** - - - `ValidationError`: input fields are validated, if these are not suitable the exception is raised - - `HTTPError`: request error to the API, 4XX or 5XX - - ---- - - - -## function `create` - -```python -create( - name: str = typer.Option( - ..., "--name", "-n", help="Name of the model to be created" - ), - description: str = typer.Option( - None, "--description", "-d", help="Description of the model to be created" - ), - debug: Optional[bool] = **DEBUG_OPTION** -) β†’ None -``` - -Command to create a model. Asks for the new model's information and validates the input, then sends the information to the API - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False). - - - -**Raises:** - - - `ValidationError`: input fields are validated, if these are not suitable the exception is raised - - `HTTPError`: request error to the API, 4XX or 5XX - - diff --git a/docs/reference/api/commands.prove.md b/docs/reference/api/commands.prove.md deleted file mode 100644 index e405a91..0000000 --- a/docs/reference/api/commands.prove.md +++ /dev/null @@ -1,33 +0,0 @@ - - - - -# module `commands.prove` - - - - - ---- - - - -## function `prove` - -```python -prove( - data: str = typer.Argument(None), - model_id: Optional[str] = typer.Option(None, "--model-id", "-m"), - version_id: Optional[str] = typer.Option(None, "--version-id", "-v"), - size: JobSize = typer.Option(JobSize.S, "--size", "-s"), - framework: Framework = typer.Option(Framework.CAIRO, "--framework", "-f"), - output_path: str = typer.Option("zk.proof", "--output-path", "-o"), - debug: Optional[bool] = DEBUG_OPTION, -) β†’ None -``` - - - - - - diff --git a/docs/reference/api/commands.reset_password.md b/docs/reference/api/commands.reset_password.md deleted file mode 100644 index 9242361..0000000 --- a/docs/reference/api/commands.reset_password.md +++ /dev/null @@ -1,126 +0,0 @@ - - - - -# module `commands.reset_password` - - - - -**Global Variables** ---------------- -- **API_HOST** - ---- - - - -## function `prompt_for_input` - -```python -prompt_for_input( - prompt_message: str, - type: Optional[type] = , - hide_input: bool = False -) β†’ str -``` - -Prompt the user for input. - - - -**Args:** - - - `prompt_message` (str): The message to display when prompting the user. - - `type` (type, optional): The type of input to expect. Defaults to str. - - `hide_input` (bool, optional): Whether to hide the input (for passwords). Defaults to False. - - - -**Returns:** - - - `str`: The user's input. - - ---- - - - -## function `handle_http_error` - -```python -handle_http_error( - e: HTTPError, - error_msg: str, - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Handle an HTTP error. - - - -**Args:** - - - `e` (HTTPError): The error to handle. - - `debug` (Optional[bool]): Whether to raise the error for debugging. Defaults to DEBUG_OPTION. - - ---- - - - -## function `request_reset_password_token` - -```python -request_reset_password_token( - email: str = typer.Option(None, "--email"), - debug: Optional[bool] = DEBUG_OPTION -) β†’ bool -``` - -Request a password reset token for a given email. - - - -**Args:** - - - `email` (str): The email to request a password reset for. - - `debug` (Optional[bool]): Whether to raise errors for debugging. Defaults to DEBUG_OPTION. - - - -**Returns:** - - - `bool`: True if the request was successful, False if not. - - ---- - - - -## function `reset_password` - -```python -reset_password( - token: str = typer.Option(None, "--token"), - debug: Optional[bool] = DEBUG_OPTION -) β†’ bool -``` - -Reset the password for a user using a reset token. - - - -**Args:** - - - `token` (str): The reset token received by email. - - `debug` (Optional[bool]): Whether to raise errors for debugging. Defaults to DEBUG_OPTION. - - - -**Returns:** - - - `bool`: True if the reset was successful, False if not. - - diff --git a/docs/reference/api/commands.transpile.md b/docs/reference/api/commands.transpile.md deleted file mode 100644 index 590a7b3..0000000 --- a/docs/reference/api/commands.transpile.md +++ /dev/null @@ -1,49 +0,0 @@ - - - - -# module `commands.transpile` - - - - -**Global Variables** ---------------- -- **API_HOST** - ---- - - - -## function `transpile` - -```python -transpile( - model_path: str = typer.Argument(None, help="Path of the model to transpile"), - output_path: str = typer.Option( - "cairo_model", "--output-path", "-o", help="Path to output the cairo model" - ) - debug: Optional[bool] = DEBUG_OPTION, -) β†’ None -``` - -Command to transpile the model using the client. Sends the model and then unzips it to the desired location. - -This command will do a couple of things behind the scenes: * Create a Model entity * Upload the model * Update the status of the model * Poll the model until the status is either FAILED or COMPLETED * If COMPLETED the model is downloaded - - - -**Args:** - - - `model_path` (str): path for the model to load - - `output_path` (str): ouput to store the transpiled model. Defaults to "cairo_model". - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION(False). - - - -**Raises:** - - - `BadZipFile`: if the received file is not a zip, could be due to a transpilation error at the API. - - `HTTPError`: request error to the API, 4XX or 5XX - - diff --git a/docs/reference/api/commands.users.md b/docs/reference/api/commands.users.md deleted file mode 100644 index 2dd8013..0000000 --- a/docs/reference/api/commands.users.md +++ /dev/null @@ -1,147 +0,0 @@ - - - - -# module `commands.users` - - - - -**Global Variables** ---------------- -- **API_HOST** - ---- - - - -## function `create` - -```python -create( - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Command to create a user. Asks for the new users information and validates the input, then sends the information to the API - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False). - - - -**Raises:** - - - `ValidationError`: input fields are validated, if these are not suitable the exception is raised - - `HTTPError`: request error to the API, 4XX or 5XX - - ---- - - - -## function `login` - -```python -login( - renew: bool = typer.Option(False, help="Force the renewal of the JWT token"), - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Logs the current user into Giza. Under the hood this will retrieve the token for the next requests. This token will be saved at `home` directory for further usage. - - - -**Args:** - - - `renew` (bool): Force the retrieval of the token to create a new one. Defaults to False. - - `debug` (Optional[bool]): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False) - - - -**Raises:** - - - `HTTPError`: request error to the API, 4XX or 5XX - - ---- - - - -## function `create_api_key` - -```python -create_api_key( - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Create an API key for your user. You need to be logged in to create an API key. The API Key will be saved at `home` directory for further usage. - - - -**Args:** - - - `debug` (Optional[bool]): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False) - - `renew` (bool): Force the retrieval of the token to create a new one. Defaults to False. - - - -**Raises:** - - - `HTTPError`: request error to the API, 4XX or 5XX - - ---- - - - -## function `me` - -```python -me( - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Retrieve information about the current user and print it as json to stdout. - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False) - - ---- - - - -## function `resend_email` - -```python -resend_email( - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Command to resend verification email. Asks for the user's email and sends the request to the API - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False). - - - -**Raises:** - - - `ValidationError`: input fields are validated, if these are not suitable the exception is raised - - `HTTPError`: request error to the API, 4XX or 5XX - - diff --git a/docs/reference/api/commands.version.md b/docs/reference/api/commands.version.md deleted file mode 100644 index 5cffba8..0000000 --- a/docs/reference/api/commands.version.md +++ /dev/null @@ -1,23 +0,0 @@ - - - - -# module `commands.version` - - - - - ---- - - - -## function `check_version` - -```python -check_version() -``` - -Check if there is a new version available of the cli in pypi to suggest upgrade - - diff --git a/docs/reference/api/commands.versions.md b/docs/reference/api/commands.versions.md deleted file mode 100644 index 1fe1eaf..0000000 --- a/docs/reference/api/commands.versions.md +++ /dev/null @@ -1,177 +0,0 @@ - - - - -# module `commands.versions` - - - - -**Global Variables** ---------------- -- **API_HOST** - ---- - - - -## function `update_sierra` - -```python -update_sierra(model_id: int, version_id: int, model_path: str) -``` - - - - - - ---- - - - -## function `get` - -```python -get( - model_id: int = typer.Option(None, help="The ID of the model"), - version_id: int = typer.Option(None, help="The ID of the version"), - debug: Optional[bool] = DEBUG_OPTION, -) β†’ None -``` - - - - - - ---- - - - -## function `transpile` - -```python -transpile( - model_path: str = typer.Argument(None, help="Path of the model to transpile"), - model_id: int = typer.Option( - None, help="The ID of the model where a new version will be created" - ), - desc: str = typer.Option(None, help="Description of the version"), - model_desc: int = typer.Option( - None, help="Description of the Model to create if model_id is not provided" - ), - framework: Framework = typer.Option(Framework.CAIRO, "--framework", "-f"), - output_path: str = typer.Option( - "cairo_model", - "--output-path", - "-o", - help="The path where the cairo model will be saved", - ), - input_data: str = typer.Option( - None, - "--input-data", - "-i", - help="The input data to use for the transpilation", - ), - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - - - - - - ---- - - - -## function `update` - -```python -update( - model_id: int = typer.Option(None, help="The ID of the model"), - version_id: int = typer.Option(None, help="The ID of the version"), - description: str = typer.Option( - None, "--description", "-d", help="New description for the version" - ), - debug: Optional[bool] = DEBUG_OPTION, -) β†’ None -``` - - - - - - ---- - - - -## function `list` - -```python -list( - model_id: int = typer.Option(None, help="The ID of the model"), - debug: Optional[bool] = DEBUG_OPTION, -) β†’ None -``` - - - - - - ---- - - - -## function `download` - -```python -download( - model_id: int = typer.Option(None, help="The ID of the model"), - version_id: int = typer.Option(None, help="The ID of the version") - output_path: str = typer.Option( - "cairo_model", "--output-path", "-o", help="Path to output the cairo model" - ), - debug: Optional[bool] = DEBUG_OPTION, -) β†’ None -``` - -Retrieve information about the current user and print it as json to stdout. - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False) - - ---- - - - -## function `download_original` - -```python -download_original( - model_id: int = typer.Option(None, help="The ID of the model"), - version_id: int = typer.Option(None, help="The ID of the version") - output_path: str = typer.Option( - "cairo_model", "--output-path", "-o", help="Path to output the cairo model" - ), - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Retrieve information about the current user and print it as json to stdout. - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False) - - diff --git a/docs/reference/api/commands.workspaces.md b/docs/reference/api/commands.workspaces.md deleted file mode 100644 index 2789bcd..0000000 --- a/docs/reference/api/commands.workspaces.md +++ /dev/null @@ -1,75 +0,0 @@ - - - - -# module `commands.workspaces` - - - - -**Global Variables** ---------------- -- **API_HOST** - ---- - - - -## function `get` - -```python -get( - debug: debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - - - - - - ---- - - - -## function `create` - -```python -create( - debug: debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - -Command to create a Giza Workspace. - - - -**Args:** - - - `debug` (Optional[bool], optional): Whether to add debug information, will show requests, extra logs and traceback if there is an Exception. Defaults to DEBUG_OPTION (False). - - - -**Raises:** - - - `ValidationError`: input fields are validated, if these are not suitable the exception is raised - - `HTTPError`: request error to the API, 4XX or 5XX - - ---- - - - -## function `delete` - -```python -delete( - debug: Optional[bool] = DEBUG_OPTION -) β†’ None -``` - - - - - - diff --git a/docs/reference/api/exceptions.md b/docs/reference/api/exceptions.md deleted file mode 100644 index 0929fe4..0000000 --- a/docs/reference/api/exceptions.md +++ /dev/null @@ -1,50 +0,0 @@ - - - - -# module `exceptions` - - - - - - ---- - - - -## class `PasswordError` - - - - - - - - ---- - - - -## class `ScarbBuildError` - - - - - - - - ---- - - - -## class `ScarbNotFound` - - - - - - - - diff --git a/docs/reference/api/options.md b/docs/reference/api/options.md deleted file mode 100644 index 62436e2..0000000 --- a/docs/reference/api/options.md +++ /dev/null @@ -1,11 +0,0 @@ - - - - -# module `options` - - - - - - diff --git a/docs/reference/api/utils.decorators.md b/docs/reference/api/utils.decorators.md deleted file mode 100644 index 73a3de6..0000000 --- a/docs/reference/api/utils.decorators.md +++ /dev/null @@ -1,40 +0,0 @@ - - - - -# module `utils.decorators` - - - - -**Global Variables** ---------------- -- **TYPE_CHECKING** - ---- - - - -## function `auth` - -```python -auth(func: Callable[~P, ~R]) β†’ Callable[~P, ~R] -``` - -Check that we have the token and it is not expired before executing - -Expects to be called from an instance of ApiClient to and endpoint that needs authorization - - - -**Args:** - - - `func` (Callable): function to decorate - - - -**Returns:** - - - `Callable`: decorated function - - diff --git a/docs/reference/api/utils.echo.md b/docs/reference/api/utils.echo.md deleted file mode 100644 index d10dbb1..0000000 --- a/docs/reference/api/utils.echo.md +++ /dev/null @@ -1,225 +0,0 @@ - - - - -# module `utils.echo` - - - - - - ---- - - - -## class `Echo` -Helper class to use when printing output of the CLI. - -Provides utilities to print different levels of the messages and provides formatting capabilities to each of the levels. - - - -### method `__init__` - -```python -__init__(debug: Optional[bool] = False) β†’ None -``` - - - - - - - - ---- - - - -### method `debug` - -```python -debug(message: str) β†’ None -``` - -Format and echo a debug message - - - -**Args:** - - - `message` (str): debug message to format and echo - ---- - - - -### method `echo` - -```python -echo(message: str, formatted: str) β†’ None -``` - -Main function to print information of a message, original message is provided as well as the formatted one. Original is used when formatting is not possible. - - - -**Args:** - - - `message` (str): original message - - `formatted` (str): formatted message - ---- - - - -### method `error` - -```python -error(message: str) β†’ None -``` - -Format and echo an error message - - - -**Args:** - - - `message` (str): error message to format and echo - ---- - - - -### method `format_debug` - -```python -format_debug(message: str) β†’ str -``` - -Specific format for debug purposes - - - -**Args:** - - - `message` (str): message to format - - - -**Returns:** - - - `str`: debug formatted message - ---- - - - -### method `format_error` - -```python -format_error(message: str) β†’ str -``` - -Specific format for error purposes - - - -**Args:** - - - `message` (str): message to format - - - -**Returns:** - - - `str`: error formatted message - ---- - - - -### method `format_message` - -```python -format_message(message: str, field: str = 'giza', color: str = 'orange3') β†’ str -``` - -Format a message with an specific field and color. Adds current time, provided field and prints it with the specified color. - - - -**Args:** - - - `message` (str): the message to format with the CLI - - `field` (str): Main field to format with the message. Defaults to "giza". - - `color` (str): Color to format the message with. Defaults to "orange3". - - - -**Returns:** - - - `str`: the formatted message - ---- - - - -### method `format_warning` - -```python -format_warning(message: str) β†’ str -``` - -Specific format for warning purposes - - - -**Args:** - - - `message` (str): message to format - - - -**Returns:** - - - `str`: error formatted message - ---- - - - -### method `info` - -```python -info(message: str) β†’ None -``` - -Format and echo a message - - - -**Args:** - - - `message` (str): message to format and echo - ---- - - - -### method `warning` - -```python -warning(message: str) β†’ None -``` - -Format and echo a warning message - - - -**Args:** - - - `message` (str): message to format and echo - - diff --git a/docs/reference/api/utils.enum.md b/docs/reference/api/utils.enum.md deleted file mode 100644 index eca5654..0000000 --- a/docs/reference/api/utils.enum.md +++ /dev/null @@ -1,2 +0,0 @@ -# utils.enum - diff --git a/docs/reference/api/utils.md b/docs/reference/api/utils.md deleted file mode 100644 index 0c124c7..0000000 --- a/docs/reference/api/utils.md +++ /dev/null @@ -1,40 +0,0 @@ - - - - -# module `utils` - - - - -**Global Variables** ---------------- -- **REQUEST_ID_HEADER** - ---- - - - -## function `get_response_info` - -```python -get_response_info(response: Response | None) β†’ Dict[str, Any] -``` - -Utility to retrieve information of the client response. - -Try to get the body, if not just get the text. - - - -**Args:** - - - `response` (Response): a response from the API - - - -**Returns:** - - - `dict`: information about the returned response - - diff --git a/docs/resources/agents.md b/docs/resources/agents.md deleted file mode 100644 index b752684..0000000 --- a/docs/resources/agents.md +++ /dev/null @@ -1,163 +0,0 @@ -# Agents - -Agents are entities designed to assist users in interacting with Smart Contracts by managing the proof verification of verifiable ML models and executing these contracts using Ape's framework. - -Agents serve as intermediaries between users and Smart Contracts, facilitating seamless interaction with verifiable ML models and executing associated contracts. They handle the verification of proofs, ensuring the integrity and authenticity of data used in contract execution. - -## Creating an agent - -To create an agent, first you need to have an endpoint already deployed and an [ape account](https://docs.apeworx.io/ape/stable/userguides/accounts.html) created locally. If you have not yet deployed an endpoint, please refer to the [endpoints](./endpoints.md) documentation. To create the ape account, you can use the `ape accounts generate` command: - -```console -$ ape accounts generate -Enhance the security of your account by adding additional random input: -Show mnemonic? [Y/n]: n -Create Passphrase to encrypt account: -Repeat for confirmation: -SUCCESS: A new account '0x766867bB2E3E1A6E6245F4930b47E9aF54cEba0C' with HDPath m/44'/60'/0'/0/0 has been added with the id '' -``` - -{% hint style="danger" %} -The passphrase must be kept secret and secure, as it is used to encrypt the account and is required to access it. The account name is used to identify the account and along with the passphrase to perform transactions in the smart contracts. -{% endhint %} - -To create an agent, users can employ the `create` command. This command facilitates the creation of an agent, allowing users to interact with deployed endpoints and execute associated contracts. - -During the creation you will be asked to select an account to create the agent. The account is used to sign the transactions in the smart contracts. - -```console -> giza agents create --model-id --version-id --name --description - -[giza][2024-04-10 11:50:24.005] Creating agent βœ… -[giza][2024-04-10 11:50:24.006] Using endpoint id to create agent, retrieving model id and version id -[giza][2024-04-10 11:50:53.480] Select an existing account to create the agent. -[giza][2024-04-10 11:50:53.480] Available accounts are: -┏━━━━━━━━━━━━━┓ -┃ Accounts ┃ -┑━━━━━━━━━━━━━┩ -β”‚ my_account β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -Enter the account name: my_account -{ - "id": 1, - "name": , - "description": , - "parameters": { - "model_id": , - "version_id": , - "endpoint_id": , - "alias": "my_account" - }, - "created_date": "2024-04-10T09:51:04.226448", - "last_update": "2024-04-10T09:51:04.226448" -} -``` - -An Agent can also be created using the `--endpoint-id` flag, which allows users to specify the endpoint ID directly. - -```console -> giza agents create --endpoint-id --name --description -``` - -## Listing agents - -The list command is designed to retrieve information about all existing agents and the parameters of them. - -```console -> giza agents list -[giza][2024-04-10 12:30:05.038] Listing agents βœ… -[ - { - "id": 1, - "name": "Agent one", - "description": "Agent to handle liquidity pools", - "parameters": { - "model_id": 1, - "version_id": 1, - "endpoint_id": 1, - "account": "awesome_account", - }, - "created_date": "2024-04-09T15:07:14.282177", - "last_update": "2024-04-10T10:06:36.928941" - }, - { - "id": 2, - "name": "Agent two", - "description": "Agent to handle volatility", - "parameters": { - "model_id": 1, - "version_id": 2, - "endpoint_id": 2, - "account": "another_awesome_account" - }, - "created_date": "2024-04-10T09:51:04.226448", - "last_update": "2024-04-10T10:12:18.975737" - } -] -``` - -## Retrieving an Agent - -For retrieving detailed information about a specific agent, users can utilize the `get` command. This command allows users view the details of a specific agent: - -```console -> giza agents get --agent-id 1 -{ - "id": 1, - "name": "Agent one", - "description": "Agent to handle liquidity pools", - "parameters": { - "model_id": 1, - "version_id": 1, - "endpoint_id": 1, - "account": "awesome_account", - }, - "created_date": "2024-04-09T15:07:14.282177", - "last_update": "2024-04-10T10:06:36.928941" -} -``` - -## Updating an Agent - -To update an agent, users can use the `update` command. This command facilitates the modification of an agent, allowing users to update the agent's name, description, and parameters. - -```console -> giza agents update --agent-id 1 --name "Agent one updated" --description "Agent to handle liquidity pools updated" --parameters chain=ethereum:mainnet:geth - -{ - "id": 1, - "name": "Agent one updated", - "description": "Agent to handle liquidity pools updated", - "parameters": { - "model_id": 1, - "version_id": 1, - "endpoint_id": 1, - "chain": "ethereum:mainnet:geth", - "account": "awesome_account", - }, - "created_date": "2024-04-10T09:51:04.226448", - "last_update": "2024-04-10T10:37:28.285500" -} -``` - -The parameters can be updated using the `--parameters` flag, which allows users to specify the parameters to be updated. - -```console -> giza agents update --agent-id 1 --parameters chain=ethereum:mainnet:geth --parameters account=awesome_account -``` - -The --parameters flag can be used multiple times to update multiple parameters and expects a key-value pair separated by an equal sign, `parameter_key=parameter_value`. - -## Delete an Agent - -For deleting an Agent, users can use the `delete` command. This command will erase any related data to the agent. - -```console -> giza agents delete --agent-id 1 -[giza][2024-04-10 12:40:33.959] Deleting agent 1 βœ… -[giza][2024-04-10 12:40:34.078] Agent 1 deleted βœ… -``` - -## More Information - -For more information about agents, and their usage in AI Actions, please refer to the [Agents](add_final_page) documentation. diff --git a/docs/resources/endpoints.md b/docs/resources/endpoints.md deleted file mode 100644 index 64665bc..0000000 --- a/docs/resources/endpoints.md +++ /dev/null @@ -1,129 +0,0 @@ -# Endpoints - -Endpoints in our platform provide a mechanism for creating services that accept predictions via a designated endpoint. These services, based on existing platform versions, leverage Cairo under the hood to ensure provable inferences. Using the CLI, users can effortlessly deploy and retrieve information about these machine learning services. - -## Deploying a model as an endpoint - -To deploy a model, you must first have a version of that model. If you have not yet created a version, please refer to the [versions](versions.md) documentation. - -To create a new service, users can employ the `deploy` command. This command facilitates the deployment of a machine learning service ready to accept predictions at the `/cairo_run` endpoint, providing a straightforward method for deploying and utilizing machine learning capabilities. - -```console -> giza endpoints deploy --model-id 1 --version-id 1 model.sierra.json -β–°β–°β–°β–°β–°β–±β–± Creating endpoint! -[giza][2024-02-07 12:31:02.498] Endpoint is successful βœ… -[giza][2024-02-07 12:31:02.501] Endpoint created with id -> 1 βœ… -[giza][2024-02-07 12:31:02.502] Endpoint created with endpoint URL: https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app πŸŽ‰ -``` - -If a model is fully compatible the sierra file is not needed and can be deployed without using it in the command: - -``` -> giza endpoints deploy --model-id 1 --version-id 1 -β–°β–°β–°β–°β–°β–±β–± Creating endpoint! -[giza][2024-02-07 12:31:02.498] Endpoint is successful βœ… -[giza][2024-02-07 12:31:02.501] Endpoint created with id -> 1 βœ… -[giza][2024-02-07 12:31:02.502] Endpoint created with endpoint URL: https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app πŸŽ‰ -``` - -{% hint style="danger" %} -For a partially compatible model the sierra file must be provided, if not an error will be shown. -{% endhint %} - -### Example request - -Now our service is ready to accept predictions at the provided endpoint URL. To test this, we can use the `curl` command to send a POST request to the endpoint with a sample input. - -```console -> curl -X POST https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app/cairo_run \ - -H "Content-Type: application/json" \ - -d '{ - "args": "[\"2\", \"2\", \"2\", \"4\", \"1\", \"2\", \"3\", \"4\"]" - }' | jq -{ - "result": [ - { - "value": { - "val": [ - 1701737587, - 1919382893, - 1869750369, - 1852252262, - 1864395887, - 1948284015, - 1231974517 - ] - } - } - ] -} -``` - -## Listing endpoints - -The list command is designed to retrieve information about all existing endpoints. It provides an overview of the deployed machine learning services, allowing users to monitor and manage multiple endpoints efficiently. - -```console -giza endpoints list -[giza][2024-01-17 17:19:00.631] Listing endpoints βœ… -[ - { - "id": 1, - "status": "COMPLETED", - "uri": "https://deployment-gizabrain-1-1-53427f44-dagsgas-ew.a.run.app", - "size": "S", - "service_name": "deployment-gizabrain-1-1-53427f44", - "model_id": 1, - "version_id": 1, - "is_active": true - }, - { - "id": 2, - "status": "COMPLETED", - "uri": "https://deployment-gizabrain-1-2-53427f44-dagsgas-ew.a.run.app", - "size": "S", - "service_name": "deployment-gizabrain-1-2-53427f44", - "model_id": 1, - "version_id": 2, - "is_active": false - } -] -``` - -Executing this command will display a list of all current endpoints, including relevant details such as service names, version numbers, and endpoint status. - -{% hint style="info" %} -To list only active endpoints you can use the flag `--only-active/-a` so only active ones are shown. -{% endhint %} - -## Retrieving an endpoint - -For retrieving detailed information about a specific endpoint, users can utilize the get command. This command allows users to query and view specific details of a single endpoint, providing insights into the configuration, status, and other pertinent information. - -```console -> giza endpoints get --endpoint-id 1 -{ - "id": 1, - "status": "COMPLETED", - "uri": "https://deployment-gizabrain-38-1-53427f44-dagsgas-ew.a.run.app", - "size": "S", - "service_name": "deployment-gizabrain-38-1-53427f44", - "model_id": 38, - "version_id": 1, - "is_active": true -} -``` - -## Delete an endpoint - -For deleting an endpoint, users can use the delete command. This command facilitates the removal of a machine learning service, allowing users to manage and maintain their deployed services efficiently. - -```console -> giza endpoints delete --endpoint-id 1 -[giza][2024-03-06 18:10:22.548] Deleting endpoint 1 βœ… -[giza][2024-03-06 18:10:22.830] Endpoint 1 deleted βœ… -``` - -{% hint style="info" %} -The endpoints are not fully deleted, so you can still access the underlying proofs generated by them. -{% endhint %} diff --git a/docs/resources/models.md b/docs/resources/models.md deleted file mode 100644 index fc898ba..0000000 --- a/docs/resources/models.md +++ /dev/null @@ -1,120 +0,0 @@ -# Models - -Handle your models at Giza! - -In Giza, a model represents a container for versions of your machine learning model. This design allows you to iterate and improve your ML model by creating new versions for it. Each model can have multiple versions, providing a robust and flexible way to manage the evolution of your ML models. This traceability feature ensures that you have a clear record of the original `onnx` model used for transpilation, who performed the transpilation, and the output generated. - -Remember, you need to be logged in to use these functionalities! - -## Create a Model - -Creating a new model in Giza is a straightforward process. You only need to provide a name for the model using the `--name` option. However, you can also add a description of the model using the `--description` option. This can be helpful for keeping track of different models and their purposes. - -Here's how you can do it: - -```console -> giza models create --name my_new_model --description "A New Model" -[giza][2023-09-13 13:24:28.223] Creating model βœ… -{ - "id": 1, - "name": "my_new_model", - "description": "A New Model" -} -``` - -Typically, the `transpile` command is used to handle model creation. During this process, the filename is checked for an existing model. If none is found, a new model is automatically created. However, manual creation of a model is also supported. For more information, refer to the transpile documentation ([cairo](../frameworks/cairo/transpile.md) and [ezkl](../frameworks/ezkl/transpile.md)). - -## List Models - -Giza provides a simple and efficient way to list all the models you have stored on the server. This feature is especially useful when you have multiple models and need to manage them effectively. - -To list all your models, you can use the `list` command. This command retrieves and displays a list of all models stored in the server. Each model's information is printed in a json format for easy readability and further processing. - -Here's how you can do it: - -```console -> giza models list -[giza][2023-09-13 13:11:39.403] Listing models βœ… -[ - { - "id": 1, - "name": "my_new_model", - "description": "A New Model" - }, - { - "id": 2, - "name": "Test", - "description": "A Model for testing different models" - } -] -``` - -## Retrieve Model Information - -You can retrieve detailed information about a model stored on the server using its unique model id. This includes its name, description, and other id: - -```console -> giza models get --model-id 1 # When we create model for you we output it in the logs so be aware -[giza][2023-09-13 13:17:53.594] Retrieving model information βœ… -{ - "id": 1, - "name": "my_new_model", - "description": "A New Model" -} -``` - -Now we can see that we have a model successfully transpiled! Now if we want we could download it again! - -## Transpile a model - -{% hint style="info" %} -**Note:** This is explained extensively in the transpile documentation ([Orion Cairo](../frameworks/cairo/transpile.md) and [EZKL](../frameworks/ezkl/transpile.md)). -{% endhint %} - -Transpiling a model in Giza is a crucial step in the model deployment process as an endpoint. Transpilation is the process of converting your machine learning model into a format that can be executed on Giza. Depending the ZKML framework chosen, this process involves converting the model into a series of Cairo instructions or performing the setup using EZKL. - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -When you execute the 'transpile' command, it initially checks for the presence of the model on the Giza platform. If no model is found, it automatically generates one and performs the transpilation. Here is an example of the command: - -``` -giza transpile --framework CAIRO awesome_model.onnx --output-path my_awesome_model -``` - -It's worth noting that if you already have created a model, you can transpile it by specifying the model ID: - -``` -giza transpile --model-id 1 --framework CAIRO awesome_model.onnx --output-path my_awesome_model -``` - -This method proves useful when you intend to create a new version of an existing model. - -For more information, refer to the transpile documentation ([cairo](../frameworks/cairo/transpile.md) and [ezkl](../frameworks/ezkl/transpile.md)). - -## Download a successfully transpiled model - -For this we can use the `download` command available in the CLI which only needs a `model_id` to download it again! - -```console -> giza models download 1 -[giza][2023-08-04 10:33:14.271] Transpilation is ready, downloading! βœ… -[giza][2023-08-04 10:33:15.134] Transpilation saved at: cairo_model -``` - -Let's check the downloaded model: - -```console -> tree cairo_model/ -cairo_model -β”œβ”€β”€ inference -β”‚ β”œβ”€β”€ Scarb.toml -β”‚ └── src -β”‚ └── lib.cairo -└── initializers - β”œβ”€β”€ node_l1 - β”‚ β”œβ”€β”€ Scarb.toml - β”‚ └── src - β”‚ └── lib.cairo -``` diff --git a/docs/resources/users.md b/docs/resources/users.md deleted file mode 100644 index 5a07106..0000000 --- a/docs/resources/users.md +++ /dev/null @@ -1,123 +0,0 @@ -# Users - -Giza CLI provides the capabilities to manage users in Giza. - -- [Users](#users) - - [Available commands](#available-commands) - - [Create](#create) - - [Login](#login) - - [Create API Key](#create-api-key) - - [Me](#me) - -## Available commands - -### Create - -Allows to create a user using the CLI. The username must be unique and the email account should not have been used previously for another user. - -```console -> giza users create - -Enter your username 😎: my-username -Enter your password πŸ₯· : (this is a secret) -Enter your email πŸ“§: gonzalo@gizatech.xyz -[giza][2023-06-23 12:29:41.417] User created βœ…. Check for a verification email πŸ“§ -``` - -This will create an *inactive* user in Giza, to activate it you need to verify your user through the verification email. - -If there is an error or you want to have more information about what it's going on there is a `--debug` flag that will add more information about the error. This will print outgoing requests to the API, debug logs and python traceback about what happened. - -⚠️**Note**: be aware that the debug option will print everything that its going to the API, in this case the password will be printed as plain text in the terminal, if you are using the debug option to fill an issue make sure to remove the credentials. - -### Login - -Log into Giza platfrom and retrieve a JWT for authentication. This JWT will be stored to authenticate you later until the token expires. - -**You need te have an active account to log in** - -```console -> giza users login - -Enter your username 😎: my-username -Enter your password πŸ₯· : -[giza][2023-06-23 12:32:17.917] Log into Giza -[giza][2023-06-23 12:32:18.716] ⛔️Could not authorize the user⛔️ -[giza][2023-06-23 12:32:18.718] ⛔️Status code -> 400⛔️ -[giza][2023-06-23 12:32:18.719] ⛔️Error message -> {'detail': 'Inactive user'}⛔️ -``` - -Once activated you can successfully log into Giza: - -```console -> giza users login - -Enter your username 😎: gizabrain -Enter your password πŸ₯· : -[giza][2023-07-12 10:52:25.199] Log into Giza -[giza][2023-07-12 10:52:46.998] Credentials written to: /Users/gizabrain/.giza/.credentials.json -[giza][2023-07-12 10:52:47.000] Successfully logged into Giza βœ… -``` - -If you want force the renewal of the token you can use `--renew` to force the log in. If the flag is not present we verify if there has been a previous log in and check that the token it's still valid. - -```console -> giza users login - -Enter your username 😎: gizabrain -Enter your password πŸ₯· : -[giza][2023-07-12 10:55:26.219] Log into Giza -[giza][2023-07-12 10:55:26.224] Token it still valid, re-using it from ~/.giza -[giza][2023-07-12 10:55:26.224] Successfully logged into Giza βœ… -``` - -With `--renew`: - -```console -> giza users login --renew - -Enter your username 😎: gizabrain -Enter your password πŸ₯· : -[giza][2023-07-12 10:56:44.316] Log into Giza -[giza][2023-07-12 10:56:44.979] Credentials written to: /Users/gizabrain/.giza/.credentials.json -[giza][2023-07-12 10:56:44.980] Successfully logged into Giza βœ… -``` - -**Note**: `--debug` its also available. - -### Create API Key - -Create an API key for the current user. This API key will be stored and will be used to authenticate the user in the future. - -**You need te have an active account to log in** - -```console -> giza users create-api-key -[giza][2024-01-17 15:27:27.936] Creating API Key βœ… -[giza][2024-01-17 15:27:53.605] API Key written to: /Users/gizabrain/.giza/.api_key.json -[giza][2024-01-17 15:27:53.606] Successfully created API Key. It will be used for future requests βœ… -``` - -Now you can use the API key to authenticate yourself withouth the need of login again and again. - -**NOTE: The usage of API key is less secure than JWT, so use it with caution.** - -### Me - -Retrieve information about the current user. - -**You need te have an active account** - -```console -> giza users me - -[giza][2023-07-12 10:59:43.821] Retrieving information about me! -[giza][2023-07-12 10:59:43.823] Token it still valid, re-using it from ~/.giza -{ - "username": "gizabrain", - "email": "gizabrain@gizatech.xyz", - "is_active": true -} -``` - -**Note**: `--debug` its also available. diff --git a/docs/resources/versions.md b/docs/resources/versions.md deleted file mode 100644 index d71d3c7..0000000 --- a/docs/resources/versions.md +++ /dev/null @@ -1,120 +0,0 @@ -# Versions - -Manage your model versions at Giza! - -In Giza, a version represents a specific iteration of your machine learning model within a Giza Model. This design allows you to iterate and improve your ML model by creating new versions for it. Each model can have multiple versions, providing a robust and flexible way to manage the evolution of your ML models. This traceability feature ensures that you have a clear record of each version of your model. - -Remember, you need to be logged in to use these functionalities! - -## Retrieve Version Information - -You can retrieve detailed information about a specific version of a model using its unique model ID and version ID. This includes its version number, size, description, status, creation date, and last update date. - -Here's how you can do it: - -```console -> giza versions get --model-id 1 --version-id 1 -[giza][2023-09-13 14:38:30.965] Retrieving version information βœ… -{ - "version": 1, - "size": 52735, - "status": "COMPLETED", - "message": "Transpilation Successful", - "description": "Initial version of the model", - "created_date": "2023-07-04T11:15:09.448709", - "last_update": "2023-08-25T11:08:51.815545" -} -``` - -## List Versions - -Giza provides a simple and efficient way to list all the versions of a specific model you have. This feature is especially useful when you have multiple versions of a model and need to manage them effectively. - -To list all your versions of a model, you can use the list command. Each version's information is printed in a json format for easy readability and further processing. - -Here's how you can do it: - -```console -> giza versions list --model-id 1 -[giza][2023-09-13 14:41:09.209] Listing versions for the model βœ… -[ - { - "version": 1, - "size": 52735, - "status": "COMPLETED", - "message": "Transpilation Successful", - "description": "Initial version of the model", - "created_date": "2023-07-04T11:15:09.448709", - "last_update": "2023-08-25T11:08:51.815545" - }, - { - "version": 2, - "size": 52735, - "status": "COMPLETED", - "message": "Transpilation Successful!", - "description": "Intial version", - "created_date": "2023-09-13T10:24:20.018476", - "last_update": "2023-09-13T10:24:24.376009" - } -] -``` - -## Transpile a Model Version - -{% hint style="info" %} -**Note:** This is explained extensively in the transpile documentation ([Orion Cairo](../frameworks/cairo/transpile.md) and [EZKL](../frameworks/ezkl/transpile.md)). -{% endhint %} - -Transpiling a model version in Giza is a crucial step in the model deployment process as an endpoint. Transpilation is the process of converting your machine learning model into a format that can be executed on Giza. Depending the ZKML framework chosen, this process involves converting the model into a series of Cairo instructions or performing the setup using EZKL. - -{% hint style="danger" %} -Currently, any related EZKL capabilities are disabled -{% endhint %} - -When you transpile a model, you're essentially creating a new version of that model. Each version represents a specific iteration of your machine learning model, allowing you to track and manage the evolution of your models effectively. - -Here's how you can transpile a model version: - -```console -> giza versions transpile --framework CAIRO awesome_model.onnx --output-path my_awesome_model -[giza][2023-09-13 12:56:43.725] No model id provided, checking if model exists βœ… -[giza][2023-09-13 12:56:43.726] Model name is: awesome_model -[giza][2023-09-13 12:56:43.978] Model Created with id -> 1! βœ… -[giza][2023-09-13 12:56:44.568] Sending model for transpilation βœ… -[giza][2023-09-13 12:56:55.577] Transpilation recieved! βœ… -[giza][2023-09-13 12:56:55.583] Transpilation saved at: cairo_model -``` - -Once the transpilation process is complete, a new version of the model is created in Giza. The version will be downloaded and saved at the specified output path, but you can also execute later with the `download` command to download it again. - -## Download a Transpiled Version - -Once a model has been successfully transpiled, it's not necessary to go through the transpilation process again. The transpiled version is stored and can be downloaded anytime you need it. This is done using the `download` command in the CLI. This command specifically requires the `model_id` and `version_id` to accurately identify and download the correct transpiled version. This feature saves time and computational resources, making the management of your models more efficient. - -{% hint style="warning" %} -The \`download\` feature is currently only available for the Orion Cairo framework. -{% endhint %} - -```console -> giza versions download --model-id 1 --version-id 1 --output-path path -[giza][2023-08-04 10:33:14.271] Transpilation is ready, downloading! βœ… -[giza][2023-08-04 10:33:15.134] Transpilation saved at: path -``` - -Let's check the downloaded version: - -```console -> tree cairo_model/ -cairo_model -β”œβ”€β”€ inference -β”‚ β”œβ”€β”€ Scarb.toml -β”‚ └── src -β”‚ └── lib.cairo -└── initializers - β”œβ”€β”€ node_l1 - β”‚ β”œβ”€β”€ Scarb.toml - β”‚ └── src - β”‚ └── lib.cairo -``` - -For more information on how to transpile a model, refer to the transpile documentation ([cairo](../frameworks/cairo/transpile.md) and [ezkl](../frameworks/ezkl/transpile.md)). diff --git a/docs/resources/workspaces.md b/docs/resources/workspaces.md deleted file mode 100644 index 58da7b4..0000000 --- a/docs/resources/workspaces.md +++ /dev/null @@ -1,63 +0,0 @@ -# Workspaces - -Workspaces in our platform are a crucial component designed to enhance user interaction with Giza Actions. These workspaces provide a user-friendly interface (UI) for managing and tracking runs, tasks, and metadata associated with action executions. Leveraging a command-line interface (CLI), users can seamlessly interact with workspaces, ensuring a smooth and efficient experience. - -The incorporation of Workspaces stems from our commitment to optimizing user interaction with Giza Actions. These dedicated workspaces serve as a strategic enhancement, providing a cohesive environment for users to oversee, manage, and delve into the intricate details of action runs, tasks, and associated metadata. The introduction of Workspaces aims to elevate user efficiency, offering a centralized hub that streamlines navigation and organization. - -## Create a Workspace - -To create a new workspace, users can utilize the giza workspace create command. This command initiates the creation process, setting up a new workspace. If a workspace with the specified name already exists, the command will gracefully handle this scenario by throwing an error, ensuring that each workspace has a unique identifier. - -The workspace creation process can take up to 10 minutes as we are creating isolated resources for each respective workspace. - -```console -> giza workspaces create -[giza][2024-01-17 14:40:02.046] Creating Workspace βœ… -[WARNING][2024-01-17 14:40:02.047] This process can take up to 10 minutes ⏳ -[giza][2024-01-17 14:41:51.248] Waiting for workspace creation... -[giza][2024-01-17 14:43:12.291] Workspace status is 'PROCESSING' -[giza][2024-01-17 14:45:54.365] Worksace creation is successful βœ… -[giza][2024-01-17 14:45:54.366] βœ… Workspace URL: https://actions-server-gizabrain-gageadsga-ew.a.run.app βœ… -``` - -Once created, the workspace will be available for use. The workspace URL will be printed in the console, and it can be used to access the workspace. - -![workspace](../.gitbook/assets/workspace.png) - -Now you can start using the workspace to run actions! - -## Retrieve a Workspace - -For retrieving information about an existing workspace, the giza workspace get command comes into play. This command provides users with a comprehensive overview of the specified workspace, including details about the url. It serves as a quick reference point to get the workspace URL for the user. - -```console -> giza workspaces get -[giza][2024-01-17 14:46:35.654] Retrieving workspace information βœ… -[giza][2024-01-17 14:46:35.805] βœ… Workspace URL: https://actions-server-gizabrain-gageadsga-ew.a.run.app βœ… -{ - "url": "https://actions-server-gizabrain-gageadsga-ew.a.run.app", - "status": "COMPLETED" -} -``` - -## Delete a Workspace - -In situations where a workspace is no longer needed, users can use the giza workspace delete command to remove it. This command ensures a clean and straightforward deletion process for an existing workspace, allowing users to manage their resources efficiently. - -It will prompt a confirmation message before deleting the workspace as **USER DATA WILL BE ERASED**. - -```console -> giza workspaces delete -[WARNING][2024-01-17 14:48:29.103] THIS WILL ERASE ALL YOUR WORKSPACE DATA ❌ -Are you sure you want to delete the workspace? [y/N]: y -[giza][2024-01-17 14:49:05.777] Deleting Workspace βœ… -[giza][2024-01-17 14:49:08.507] Workspace Deleted βœ… -``` - -## About Giza Actions - -Giza Actions is the core component within the platform, Workspaces act as an interface to connect with these actions, providing users with a centralized hub to monitor and manage their executions. This integration enhances the overall usability and accessibility of Giza Actions, making it easier for users to interact with and control their workflows. - -By integrating workspaces into our platform, we aim to simplify the user experience, offering a powerful yet intuitive solution for managing Giza Actions effectively. - -The Actions-SDK can be found at: [https://actions.gizatech.xyz/welcome/giza-actions-sdk](https://actions.gizatech.xyz/welcome/giza-actions-sdk) diff --git a/docs/welcome/actions.md b/docs/welcome/actions.md deleted file mode 100644 index 05d533c..0000000 --- a/docs/welcome/actions.md +++ /dev/null @@ -1,42 +0,0 @@ -# Actions - -Build Verifiable ML products with ease. - -Giza Actions empowers developers to build and scale Verifiable ML solutions quickly, turning their python scripts and ML models into resilient, recurrent workflows. Every model contained in an Action has verifiability properties without any code change using ZKML with and Giza Platform. - -At the core of Giza Actions are Actions themselves. An action serves as a framework for coding ML inferencing workflow logic, enabling users to tailor the behaviour of their workflows. Defined as Python functions, any Python function has the potential to be transformed into an action. - -More information about Giza Actions can be found in the [Actions Documentation](https://actions.gizatech.xyz/concepts/actions). - -## Starting with Actions - -Jumpstarting the creation of actions is made efficient through the use of a template powered by [Cookiecutter](https://github.com/cookiecutter/cookiecutter). This template serves as a foundation for creating actions and pipelines, streamlining the development process. The `actions-sdk` provides the necessary tools to create, visualize, and monitor these pipelines, enabling users to deploy and manage their actions seamlessly. - -```console -> giza actions new actions_project -[giza][2024-01-18 11:38:43.180] Creating a new Action project with name: actions_project βœ… -[giza][2024-01-18 11:38:44.173] Action project created successfully at ./actions_project βœ… -``` - -This will create a new directory with the following structure: - -```console -> tree actions_project -actions_project -β”œβ”€β”€ README.md -β”œβ”€β”€ actions_project -β”‚ β”œβ”€β”€ __init__.py -β”‚ └── action.py -β”œβ”€β”€ pyproject.toml -└── tests - └── __init__.py - -3 directories, 5 files -``` - -## Related Topics - -* [Actions SDK](https://actions.gizatech.xyz/welcome/giza-actions-sdk) -* [Workspace](../resources/workspaces.md) -* [Models](../resources/models.md) -* [Versions](../resources/versions.md) diff --git a/docs/welcome/authentication.md b/docs/welcome/authentication.md deleted file mode 100644 index 8c7e887..0000000 --- a/docs/welcome/authentication.md +++ /dev/null @@ -1,21 +0,0 @@ -# Authentication - -Authentication is a critical aspect of our platform, ensuring secure access to resources. Currently, there are two primary methods for authentication: the usage of JSON Web Tokens (JWT) through the giza users login command and the utilization of API keys. - -## What are JWT and API keys? - -* *JWT (JSON Web Token)*: A JWT is a compact, URL-safe means of representing claims between two parties. In the context of our platform, it serves as a secure authentication token obtained through the giza users login command. This token is then used to establish and maintain a secure communication channel with the platform. - -* *API Key*: An API key is a unique alphanumeric code generated by the platform that provides a secure way for applications or users to authenticate themselves. Once created, an API key serves as a credential to communicate with the platform, eliminating the need for repeated login procedures. - -## Key Differences - -The primary distinction between JWT and API keys lies in their nature and usage: - -* JWT is a token-based authentication mechanism that is time-sensitive and typically used for short-lived authentication sessions. - -* API keys, on the other hand, are static credentials that persist and provide a more long-term solution for authentication without the need for frequent renewals. - -## How to authenticate - -For information about using the CLI to authenticate yourself please refer to the [users](../resources/users.md) documentation. diff --git a/docs/welcome/frameworks.md b/docs/welcome/frameworks.md deleted file mode 100644 index 91c14bd..0000000 --- a/docs/welcome/frameworks.md +++ /dev/null @@ -1,37 +0,0 @@ -# Frameworks - -Giza operates on multiple frameworks simultaneously. This allows you to switch between frameworks as needed, providing flexibility and control over your development process. - -## Orion Cairo - -_Cairo_ is A [STARK](https://starkware.co/stark/)-based Turing-complete language for writing provable programs. It is designed to be highly expressive, allowing developers to write programs that are both complex and efficient. [Orion](https://orion.gizatech.xyz/welcome/readme) is an open-source, framework dedicated to Provable Machine Learning writing in Cairo. It provides essential components and a new ONNX runtime for building verifiable Machine Learning models using STARKs. - -## EZKL - -`ezkl` is an engine for doing inference for deep learning models and other computational graphs in a zk-snark using `halo2` as the backend. For more information about `ezkl`, see the [ezkl repository](https://github.com/zkonduit/ezkl) - -## Switching between frameworks - -As we aim to bring the best of both worlds to developers, Giza allows us to perform the same operations on both frameworks just with a single change in the command line, the `--framework` flag. - -This flag allows you to specify which framework you want to use for the current operation but the underlying work that we do is the same. - -For example, if you want to use the Cairo framework, you would use the `--framework CAIRO` flag. Similarly, for the EZKL framework, you would use the `--framework EZKL` flag. - -For example, if you want to transpile a program using the Cairo framework, you would use the following command: - -```bash -giza transpile --framework CAIRO model.onnx -``` - -Similarly, if you want to transpile a program using the EZKL framework, you would use the following command: - -```bash -giza transpile --framework EZKL --input-data input.json model.onnx -``` - -The `transpile` command in EZKL is essentially the same as the `setup()` command used to perform the trusted setup, as we need extra information to perform the `setup` it has an additional `--input-data` flag that allows you to specify the input data for the model. - -This allows you to switch between frameworks as needed, providing flexibility and control over your development process. - -For more information about the available commands for each framework, please refer to the [Cairo](../frameworks/cairo/) and [EZKL](../frameworks/ezkl/) documentation. diff --git a/docs/welcome/installation.md b/docs/welcome/installation.md deleted file mode 100644 index e763f20..0000000 --- a/docs/welcome/installation.md +++ /dev/null @@ -1,53 +0,0 @@ -# Installation - -## Handling Python versions with Pyenv - -As we are using Python 3.11, it's recommended to use [Pyenv](https://github.com/pyenv/pyenv) to manage your Python versions. Here are the steps to install Pyenv and set Python 3.11 as your local version: - -1. First, we need to get pyenv, for information about how to install it, please refer to the [official documentation](https://github.com/pyenv/pyenv) -2. Install Python 3.11 with Pyenv: - -```bash -pyenv install 3.11.5 -``` - -3. Set Python 3.11 as the local version for your project: - -```bash -pyenv local 3.11.5 -``` - -Now, your terminal session will use Python 3.11 for this project. - -## Recommended installation with pipx - -[pipx](https://pypa.github.io/pipx/) allows the installation of the dependency in an isolated environment. With this, we can make sure that it does not conflict with any of our installed dependencies. - -```bash -pipx install giza-cli -``` - -## Install from PyPi - -For the latest release: - -```bash -pip install giza-cli -``` - -## Installing from source - -Clone the repository and install it with `pip`: - -```bash -git clone git@github.com:gizatechxyz/giza-cli.git -cd giza-cli -pip install . -``` - -Or install it directly from the repo: - -```bash -pip install git+ssh://git@github.com/gizatechxyz/giza-cli.git -``` -