diff --git a/404.html b/404.html index 88a88e0..779024d 100644 --- a/404.html +++ b/404.html @@ -355,6 +355,90 @@ + + + + + +
  • + + How to configure GreatAI + +
  • + + + + + + + + + +
  • + + How to use a GreatAI service + +
  • + + + + + + + + + +
  • + + How to handle training data + +
  • + + + + + + + + + +
  • + + How to use LargeFile + +
  • + + + + + + + + + +
  • + + None + +
  • + + + + + + + + + +
  • + + Scraping + +
  • + + + + @@ -396,7 +480,7 @@
  • - Reference + GreatAI reference
  • @@ -458,6 +542,115 @@ + +
  • + + + + + + + + + + +
  • + + + + + + + + + +
  • Explanation diff --git a/examples/simple-mag/train/index.html b/examples/simple-mag/train/index.html index 9493387..0b8354b 100644 --- a/examples/simple-mag/train/index.html +++ b/examples/simple-mag/train/index.html @@ -360,6 +360,90 @@ + + + + + +
  • + + How to configure GreatAI + +
  • + + + + + + + + + +
  • + + How to use a GreatAI service + +
  • + + + + + + + + + +
  • + + How to handle training data + +
  • + + + + + + + + + +
  • + + How to use LargeFile + +
  • + + + + + + + + + +
  • + + None + +
  • + + + + + + + + + +
  • + + Scraping + +
  • + + + + @@ -401,7 +485,7 @@
  • - Reference + GreatAI reference
  • @@ -463,6 +547,115 @@ + +
  • + + + + + + + + + + +
  • + + + + + + + + + +
  • Explanation diff --git a/examples/simple/data/data.ipynb b/examples/simple/data/data.ipynb index 1443c7c..c3cc4b4 100644 --- a/examples/simple/data/data.ipynb +++ b/examples/simple/data/data.ipynb @@ -207,10 +207,10 @@ "output_type": "stream", "text": [ "\u001b[38;5;226m2022-06-25 14:25:24,989 | WARNING | Environment variable ENVIRONMENT is not set, defaulting to development mode ‼️\u001b[0m\n", - "\u001b[38;5;39m2022-06-25 14:25:24,990 | INFO | Found credentials file (/data/projects/great_ai_example/mongo.ini), initialising MongodbDriver\u001b[0m\n", + "\u001b[38;5;39m2022-06-25 14:25:24,990 | INFO | Found credentials file (/data/projects/great_ai_example/mongo.ini), initialising MongoDbDriver\u001b[0m\n", "\u001b[38;5;39m2022-06-25 14:25:24,991 | INFO | Found credentials file (/data/projects/great_ai_example/mongo.ini), initialising LargeFileMongo\u001b[0m\n", "\u001b[38;5;39m2022-06-25 14:25:24,992 | INFO | Settings: configured βœ…\u001b[0m\n", - "\u001b[38;5;39m2022-06-25 14:25:24,993 | INFO | πŸ”© tracing_database: MongodbDriver\u001b[0m\n", + "\u001b[38;5;39m2022-06-25 14:25:24,993 | INFO | πŸ”© tracing_database: MongoDbDriver\u001b[0m\n", "\u001b[38;5;39m2022-06-25 14:25:24,994 | INFO | πŸ”© large_file_implementation: LargeFileMongo\u001b[0m\n", "\u001b[38;5;39m2022-06-25 14:25:24,994 | INFO | πŸ”© is_production: False\u001b[0m\n", "\u001b[38;5;39m2022-06-25 14:25:24,995 | INFO | πŸ”© should_log_exception_stack: True\u001b[0m\n", diff --git a/examples/simple/data/index.html b/examples/simple/data/index.html index 25ea6cf..f7ca21b 100644 --- a/examples/simple/data/index.html +++ b/examples/simple/data/index.html @@ -360,6 +360,90 @@ + + + + + +
  • + + How to configure GreatAI + +
  • + + + + + + + + + +
  • + + How to use a GreatAI service + +
  • + + + + + + + + + +
  • + + How to handle training data + +
  • + + + + + + + + + +
  • + + How to use LargeFile + +
  • + + + + + + + + + +
  • + + None + +
  • + + + + + + + + + +
  • + + Scraping + +
  • + + + + @@ -401,7 +485,7 @@
  • - Reference + GreatAI reference
  • @@ -462,6 +546,194 @@ + + + + +
  • + + + + + + + + + + +
  • + + + + + + + + +
  • @@ -2020,10 +2292,10 @@ add_ground_truth(X, y, train_split_ratio=0.8, test_split_ratio=0.2)
  • @@ -401,7 +485,7 @@
  • - Reference + GreatAI reference
  • @@ -462,6 +546,160 @@ + + + + +
  • + + + + + + + + + + +
  • + + + + + + + + +
  • @@ -1757,10 +1995,10 @@ def get_label(
    2022-06-25 14:57:20,629 |  WARNING | Environment variable ENVIRONMENT is not set, defaulting to development mode ‼️
    -2022-06-25 14:57:20,629 |     INFO | Found credentials file (/data/projects/great_ai_example/mongo.ini), initialising MongodbDriver
    +2022-06-25 14:57:20,629 |     INFO | Found credentials file (/data/projects/great_ai_example/mongo.ini), initialising MongoDbDriver
     2022-06-25 14:57:20,630 |     INFO | Found credentials file (/data/projects/great_ai_example/mongo.ini), initialising LargeFileMongo
     2022-06-25 14:57:20,631 |     INFO | Settings: configured βœ…
    -2022-06-25 14:57:20,631 |     INFO | πŸ”© tracing_database: MongodbDriver
    +2022-06-25 14:57:20,631 |     INFO | πŸ”© tracing_database: MongoDbDriver
     2022-06-25 14:57:20,631 |     INFO | πŸ”© large_file_implementation: LargeFileMongo
     2022-06-25 14:57:20,632 |     INFO | πŸ”© is_production: False
     2022-06-25 14:57:20,633 |     INFO | πŸ”© should_log_exception_stack: True
    @@ -1991,6 +2229,42 @@ class="
           
             
  • @@ -401,7 +485,7 @@
  • - Reference + GreatAI reference
  • @@ -462,6 +546,187 @@ + + + + +
  • + + + + + + + + + + +
  • + + + + + + + + +
  • @@ -1668,10 +1933,10 @@ y = [domain for d in data for domain in d.feedback]
  • @@ -401,7 +485,7 @@
  • - Reference + GreatAI reference
  • @@ -462,6 +546,115 @@ + + +
  • + + + + + + + + + + +
  • + + + + + + + + + @@ -523,7 +716,7 @@

    Explanation#

    A lot more details and discussion about the problem context and approaches of GreatAI can be found in my thesis.

    -

    : Download

    +

    : Download


    @@ -531,7 +724,7 @@ Last update: - July 9, 2022 + July 11, 2022 @@ -552,7 +745,7 @@ @@ -396,7 +485,7 @@
  • - Reference + GreatAI reference
  • @@ -458,6 +547,115 @@ + +
  • + + + + + + + + + + +
  • + + + + + + + + + +
  • Explanation @@ -483,6 +681,8 @@ + + @@ -503,16 +703,14 @@ -

    Call remote

    - - +

    Call remote GreatAI instances#


    Last update: - July 10, 2022 + July 11, 2022 diff --git a/how-to-guides/configure-service/configure-service.md b/how-to-guides/configure-service/configure-service.md new file mode 100644 index 0000000..47534fa --- /dev/null +++ b/how-to-guides/configure-service/configure-service.md @@ -0,0 +1,101 @@ +# How to configure GreatAI + +GreatAI aims to provide reasonable defaults wherever possible. The current configuration is always prominently displayed (and updated) on the dashboard and in the command-line startup banner. + +## Using [great_ai.configure][] + +You can override any of the default settings by calling [great_ai.configure][]. If you don't call `configure`, the default settings are applied on the first call to most `great-ai` functions. + +!!! warning + You must call [great_ai.configure][] before calling (or decorating with) any other `great-ai` function. However, importing other functions before calling [great_ai.configure][] is permitted. + +```python title="configure-demo.py" +from great_ai import configure, RouteConfig +import logging + +configure( + version='1.0.0', + log_level=logging.INFO, + seed=2, + should_log_exception_stack=False, + prediction_cache_size=0, #(1) + disable_se4ml_banner=True, + dashboard_table_size=200, + route_config=RouteConfig( #(2) + feedback_endpoints_enabled=False, + dashboard_enabled=False + ) +) +``` + +1. Completely disable caching. +2. The unspecified routes are enabled by default. + +## Using remote storage + +The only aspect that cannot be automated is choosing the backing storage for the database and file storage. + +Right now, you have 3 options for storing the models and large datasets: [great_ai.large_file.LargeFileLocal][], [great_ai.large_file.LargeFileMongo][], and [great_ai.large_file.LargeFileS3][]. + +Without explicit configuration, [great_ai.large_file.LargeFileLocal][] is selected by default. This one still version-controls your files but it only stores them in a local path. + +!!! important + If your working directory contains a `mongo.ini` or `s3.ini` file, an attempt is made to auto-configure [LargeFileMongo][great_ai.large_file.LargeFileMongo] or [LargeFileS3][great_ai.large_file.LargeFileS3] respectively. + +To use [LargeFileMongo][great_ai.large_file.LargeFileMongo] or [LargeFileS3][great_ai.large_file.LargeFileS3] explicitly, configure them before calling any other `great-ai` function. + +### S3-compatible + +```toml title="s3.ini" +aws_region_name = eu-west-2 +aws_access_key_id = MY_AWS_ACCESS_KEY # ENV:MY_AWS_ACCESS_KEY would also work +aws_secret_access_key = MY_AWS_SECRET_KEY +large_files_bucket_name = bucket-for-models +``` + +```python title="use-s3.py" +from great_ai.large_file import LargeFileS3 +from great_ai import save_model + +LargeFileS3.configure_credentials_from_file('s3.ini') #(1) + +model = [4, 3] +save_model(model, 'my-model') +``` + +1. This line isn't strictly necceseary because if `s3.ini` (or `mongo.ini`) is available in the current working directory, they are automatically used to configure their respective LargeFile implementations/databases. + +??? note "Departing from AWS" + With the `aws_endpoint_url` argument, it is possible to use any other S3-compatible service such as [Backblaze](https://www.backblaze.com/){ target=_blank }. In that case, it would be `aws_endpoint_url=https://s3.us-west-002.backblazeb2.com`. + +### GridFS + +[GridFS](https://www.mongodb.com/docs/manual/core/gridfs/#:~:text=GridFS%20is%20a%20specification%20for,chunk%20as%20a%20separate%20document.){ target=_blank } specifies how to store files in MongoDB. The official MongoDB server and many compatible implementations support it. + +```toml title="mongo.ini" +MONGO_CONNECTION_STRING=mongodb://localhost:27017 # this is the default value +# if `MONGO_CONNECTION_STRING` is specified, this default is overridden +MONGO_CONNECTION_STRING=ENV:MONGO_CONNECTION_STRING +MONGO_DATABASE=my-database # it is automatically created if doesn't exist +``` + +```python title="use-mongo.py" +from great_ai.large_file import LargeFileMongo +from great_ai import save_model + +LargeFileMongo.configure_credentials_from_file('mongo.ini') + +model = [4, 3] +save_model(model, 'my-model') +``` + +!!! note "Simplifying config files" + You can combine `mongo.ini` or `s3.ini` with your application's config file because the unneeded keys are ignored by the `configure_credentials_from_file` method. + +## Using a database + +By default, a thread-safe version of [TinyDB](https://tinydb.readthedocs.io/en/latest/){ target=_blank } is utilised for saving the prediction traces into a local file. Unfortunately, for most production needs, this method is not suitable. + +### MongoDB + +At the moment, only MongoDB is supported as a production-ready `TracingDatabase`. In order to use it, you have to either place a file named `mongo.ini` in your working directory, or explicitly call [MongoDbDriver.configure_credentials_from_file][great_ai.MongoDbDriver.configure_credentials_from_file] or [MongoDbDriver.configure_credentials][great_ai.MongoDbDriver.configure_credentials]. diff --git a/how-to-guides/configure-service/index.html b/how-to-guides/configure-service/index.html new file mode 100644 index 0000000..31d2fef --- /dev/null +++ b/how-to-guides/configure-service/index.html @@ -0,0 +1,1053 @@ + + + + + + + + + + + + + + + + + + + + How to configure GreatAI - GreatAI documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + +
    +
    + + + + + + + + + + + +

    How to configure GreatAI#

    +

    GreatAI aims to provide reasonable defaults wherever possible. The current configuration is always prominently displayed (and updated) on the dashboard and in the command-line startup banner.

    +

    Using great_ai.configure#

    +

    You can override any of the default settings by calling great_ai.configure. If you don't call configure, the default settings are applied on the first call to most great-ai functions.

    +
    +

    Warning

    +

    You must call great_ai.configure before calling (or decorating with) any other great-ai function. However, importing other functions before calling great_ai.configure is permitted.

    +
    +
    configure-demo.py
    from great_ai import configure, RouteConfig
    +import logging
    +
    +configure(
    +    version='1.0.0',
    +    log_level=logging.INFO,
    +    seed=2,
    +    should_log_exception_stack=False, 
    +    prediction_cache_size=0,  #(1)
    +    disable_se4ml_banner=True,
    +    dashboard_table_size=200,
    +    route_config=RouteConfig(  #(2)
    +        feedback_endpoints_enabled=False,
    +        dashboard_enabled=False
    +    )
    +)
    +
    +
      +
    1. Completely disable caching.
    2. +
    3. The unspecified routes are enabled by default.
    4. +
    +

    Using remote storage#

    +

    The only aspect that cannot be automated is choosing the backing storage for the database and file storage.

    +

    Right now, you have 3 options for storing the models and large datasets: great_ai.large_file.LargeFileLocal, great_ai.large_file.LargeFileMongo, and great_ai.large_file.LargeFileS3.

    +

    Without explicit configuration, great_ai.large_file.LargeFileLocal is selected by default. This one still version-controls your files but it only stores them in a local path.

    +
    +

    Important

    +

    If your working directory contains a mongo.ini or s3.ini file, an attempt is made to auto-configure LargeFileMongo or LargeFileS3 respectively.

    +
    +

    To use LargeFileMongo or LargeFileS3 explicitly, configure them before calling any other great-ai function.

    +

    S3-compatible#

    +
    s3.ini
    aws_region_name = eu-west-2
    +aws_access_key_id = MY_AWS_ACCESS_KEY  # ENV:MY_AWS_ACCESS_KEY would also work
    +aws_secret_access_key = MY_AWS_SECRET_KEY
    +large_files_bucket_name = bucket-for-models
    +
    +
    use-s3.py
    from great_ai.large_file import LargeFileS3
    +from great_ai import save_model
    +
    +LargeFileS3.configure_credentials_from_file('s3.ini') #(1)
    +
    +model = [4, 3]
    +save_model(model, 'my-model')
    +
    +
      +
    1. This line isn't strictly necceseary because if s3.ini (or mongo.ini) is available in the current working directory, they are automatically used to configure their respective LargeFile implementations/databases.
    2. +
    +
    +Departing from AWS +

    With the aws_endpoint_url argument, it is possible to use any other S3-compatible service such as Backblaze. In that case, it would be aws_endpoint_url=https://s3.us-west-002.backblazeb2.com.

    +
    +

    GridFS#

    +

    GridFS specifies how to store files in MongoDB. The official MongoDB server and many compatible implementations support it.

    +
    mongo.ini
    MONGO_CONNECTION_STRING=mongodb://localhost:27017  # this is the default value
    +# if `MONGO_CONNECTION_STRING` is specified, this default is overridden
    +MONGO_CONNECTION_STRING=ENV:MONGO_CONNECTION_STRING
    +MONGO_DATABASE=my-database  # it is automatically created if doesn't exist
    +
    +
    use-mongo.py
    from great_ai.large_file import LargeFileMongo
    +from great_ai import save_model
    +
    +LargeFileMongo.configure_credentials_from_file('mongo.ini')
    +
    +model = [4, 3]
    +save_model(model, 'my-model')
    +
    +
    +

    Simplifying config files

    +

    You can combine mongo.ini or s3.ini with your application's config file because the unneeded keys are ignored by the configure_credentials_from_file method.

    +
    +

    Using a database#

    +

    By default, a thread-safe version of TinyDB is utilised for saving the prediction traces into a local file. Unfortunately, for most production needs, this method is not suitable.

    +

    MongoDB#

    +

    At the moment, only MongoDB is supported as a production-ready TracingDatabase. In order to use it, you have to either place a file named mongo.ini in your working directory, or explicitly call [MongoDbDriver.configure_credentials_from_file][great_ai.MongoDbDriver.configure_credentials_from_file] or MongoDbDriver.configure_credentials.

    + +
    +
    + + + Last update: + July 11, 2022 + + + +
    + + + +
    + +
    +
    + +
    + + + +
    +
    +
    +
    + + + + + + + + \ No newline at end of file diff --git a/how-to-guides/create-service/create-service.md b/how-to-guides/create-service/create-service.md index 632b4a1..210bdd7 100644 --- a/how-to-guides/create-service/create-service.md +++ b/how-to-guides/create-service/create-service.md @@ -1,6 +1,6 @@ # How to create a GreatAI service -The core value of `great-ai` lies in its [GreatAI][great_ai.deploy.GreatAI] class. In order to take advantage of it, you need to create an instance wrapping your code. +The core value of `great-ai` lies in its [GreatAI][great_ai.GreatAI] class. In order to take advantage of it, you need to create an instance wrapping your code. Let's say that you have the following greeter function: @@ -9,7 +9,7 @@ def my_greeter_function(your_name): return f'Hi {your_name}!' ``` -You can simply decorate (wrap) this function using the [@GreatAI.create][great_ai.deploy.GreatAI.create] factory. +You can simply decorate (wrap) this function using the [@GreatAI.create][great_ai.GreatAI.create] factory. ```python title="greeter.py" from great_ai import GreatAI @@ -20,7 +20,7 @@ def greeter(your_name): ``` ??? info "Why not simply use `@GreatAI?`" - The purpose of the [@GreatAI.create][great_ai.deploy.GreatAI.create] is simply to provide you with type-checking through MyPy, Pylance, and similar libraries. However, the overloading support for `__new__` is lacking in MyPy, thus, a static factory method is used instead. + The purpose of the [@GreatAI.create][great_ai.GreatAI.create] is simply to provide you with type-checking through MyPy, Pylance, and similar libraries. However, the overloading support for `__new__` is lacking in MyPy, thus, a static factory method is used instead. ## With types @@ -52,9 +52,9 @@ async def async_greeter(your_name: str) -> str: ## With decorators -GreatAI can decorate already decorated functions. The only restriction is that [@GreatAI.create][great_ai.deploy.GreatAI.create] always has to come last. There are two built-in decorators that you can use to customise your function but you can you use any third-party decorator as well. +GreatAI can decorate already decorated functions. The only restriction is that [@GreatAI.create][great_ai.GreatAI.create] always has to come last. There are two built-in decorators that you can use to customise your function but you can you use any third-party decorator as well. -### Using `use_model` +### Using `@use_model` If you have previously saved a model with [save_model][great_ai.save_model], you can inject it into your function by calling [@use_model][great_ai.use_model]. @@ -72,14 +72,14 @@ assert type_safe_greeter('Andras').output == 'Hi Andras' 1. By default, the parameter named `model` will be replaced by the loaded model. This behaviour can be customised by setting the `model_kwarg_name`. This way, even multiple models can be injected into a single function. !!! important - You must call [@use_model][great_ai.use_model] before [@GreatAI.create][great_ai.deploy.GreatAI.create]. Feel free to use [@use_model][great_ai.use_model] in other places of the codebase, it works equally well outside of GreatAI services. + You must call [@use_model][great_ai.use_model] before [@GreatAI.create][great_ai.GreatAI.create]. Feel free to use [@use_model][great_ai.use_model] in other places of the codebase, it works equally well outside of GreatAI services. -### Using `parameter` +### Using `@parameter` If you wish to turn of logging or specify custom validation for your parameters, you can use the [@parameter][great_ai.parameter] decorator. !!! note - By default, all parameters that are not affected by an explicit [@parameter][great_ai.parameter] or [@use_model][great_ai.use_model] are automatically decorated with [@parameter][great_ai.parameter] when [@GreatAI.create][great_ai.deploy.GreatAI.create] is called. + By default, all parameters that are not affected by an explicit [@parameter][great_ai.parameter] or [@use_model][great_ai.use_model] are automatically decorated with [@parameter][great_ai.parameter] when [@GreatAI.create][great_ai.GreatAI.create] is called. ```python title="greeter_with_validation.py" from great_ai import GreatAI, use_model @@ -93,7 +93,7 @@ assert type_safe_greeter('Andras').output == 'Hi Andras' ``` !!! important - You must call [@parameter][great_ai.parameter] before [@GreatAI.create][great_ai.deploy.GreatAI.create]. Feel free to use [@parameter][great_ai.parameter] in other places of the codebase, it works equally well outside of GreatAI services. + You must call [@parameter][great_ai.parameter] before [@GreatAI.create][great_ai.GreatAI.create]. Feel free to use [@parameter][great_ai.parameter] in other places of the codebase, it works equally well outside of GreatAI services. ## Complex example diff --git a/how-to-guides/create-service/index.html b/how-to-guides/create-service/index.html index 3c39991..eee347d 100644 --- a/how-to-guides/create-service/index.html +++ b/how-to-guides/create-service/index.html @@ -411,14 +411,14 @@
  • - Using use_model + Using @use_model
  • - Using parameter + Using @parameter
  • @@ -444,6 +444,90 @@ + + + + + +
  • + + How to configure GreatAI + +
  • + + + + + + + + + +
  • + + How to use a GreatAI service + +
  • + + + + + + + + + +
  • + + How to handle training data + +
  • + + + + + + + + + +
  • + + How to use LargeFile + +
  • + + + + + + + + + +
  • + + None + +
  • + + + + + + + + + +
  • + + Scraping + +
  • + + + + @@ -485,7 +569,7 @@
  • - Reference + GreatAI reference
  • @@ -547,6 +631,115 @@ + +
  • + + + + + + + + + + +
  • + + + + + + + + + +
  • Explanation @@ -605,14 +798,14 @@
  • - Using use_model + Using @use_model
  • - Using parameter + Using @parameter
  • @@ -688,7 +881,7 @@

    With decorators#

    GreatAI can decorate already decorated functions. The only restriction is that @GreatAI.create always has to come last. There are two built-in decorators that you can use to customise your function but you can you use any third-party decorator as well.

    -

    Using use_model#

    +

    Using @use_model#

    If you have previously saved a model with save_model, you can inject it into your function by calling @use_model.

    greeter_with_model.py
    from great_ai import GreatAI, use_model
     
    @@ -706,7 +899,7 @@
     

    Important

    You must call @use_model before @GreatAI.create. Feel free to use @use_model in other places of the codebase, it works equally well outside of GreatAI services.

    -

    Using parameter#

    +

    Using @parameter#

    If you wish to turn of logging or specify custom validation for your parameters, you can use the @parameter decorator.

    Note

    @@ -785,13 +978,13 @@ - @@ -504,28 +769,22 @@ - + -

    How to use a GreatAI service#

    -

    After creating a GreatAI service by wrapping your prediction function, it's time to do some prediction.

    -

    Let's use the following example:

    -

    ```python "type_safe_greeter.py" -from great_ai import GreatAI

    -

    @GreatAI.create -def type_safe_greeter(your_name: str) -> str: - return f'Hi {your_name}' -```

    +

    How to handle training data#

    +

    Upload data#

    +

    Use feedback#


    Last update: - July 10, 2022 + July 11, 2022 @@ -542,6 +801,42 @@ def type_safe_greeter(your_name: str) -> str:
    @@ -1596,7 +1906,7 @@ async with httpx.AsyncClient( Last update: - July 9, 2022 + July 11, 2022 @@ -1613,6 +1923,42 @@ async with httpx.AsyncClient(