readme: # IBAN Validator Model
  
  > ML model for validating IBAN account numbers.
  
  This is an open-source project which delivers a machine learning model for validating [IBAN](https://www.iso13616.org)
  account numbers accessible via [gRPC](#grpc-service) and [REST](#rest-api) APIs.
  
  The [trained model](#trained-model) is distributed in two forms:
  
   - As a [Notebook at Kaggle](https://www.kaggle.com/code/brunosantanna/iban-validator-model/notebook) for interactive experimentation.
   - As a [Docker Image](https://hub.docker.com/r/bsantanna/iban-validator-model) which contains all
  runtime [dependencies](#dependencies) and is used now as basis example for cloud related projects.
  
  The project source code is available at [bsantanna/iban-validator-model](https://github.com/bsantanna/iban-validator-model) Github repository.
  
  
  
  ## Table of contents
  
  * [Container Image](#container-image)
  * [Usage example](#usage-example)
  * [Project description](#project-description)
    * [The challenge](#the-challenge)
    * [The proposed solution](#the-proposed-solution)
    * [Dependencies](#dependencies)
    * [Trained Model](#trained-model)
    * [Module organization](#module-organization)
      * [Training](#training)
      * [Prediction](#prediction)
        * [gRPC Service](#grpc-service)
        * [REST API](#rest-api)
  * [Conclusion and references](#conclusion-and-references)
  * [Changelog](#changelog)
  * [License](#license)
  
  
  
  ## Container Image
  
  One deliverable of this project is
  a [Docker Image](https://hub.docker.com/r/bsantanna/iban-validator-model) which can be used following
  this [project license](#license).
  
  > Disclaimer:
  >
  > - The dataset may be outdated in comparison to the latest IBAN registry / country information.
  > - This model was created for case study purposes and may predict incorrect results.
  > - Use the model at your own discretion.
  
  To run this image with Docker use the following command:
  
  ```bash
  $ docker run -it --rm -p 41151:41151 -p 8080:8080 bsantanna/iban-validator-model
  ```
  
  After some moments a container should spawn two processes:
  
  - A Python [gRPC](#grpc-service) listening on port 41151.
  - A Spring Boot / Java [REST API](#rest-api) listening on port 8080.
  
  
  
  > Apple Silicon users:
  > 
  > - To run the docker image use this alternative tag: `bsantanna/iban-validator-model:aarch64`
  > - To run the notebooks of this repository, consider [following these instructions](https://developer.apple.com/metal/tensorflow-plugin/).
  >
  
  
  
  ## Usage example
  
  ![IBAN validation use case](doc/assets/validation_use_case.png)
  
  With example IBAN accounts from [https://bank.codes](https://bank.codes/iban/examples/).
  
  IBAN to validation data JSON:
  
  ```bash
  $ curl -s \
    "http://localhost:8080/validation?iban=BR1800000000141455123924100C2"
  ```
  
  Gives the following result output:
  
  ```json
  {
    "classification": {
      "bban_regex": "[0-9]{23}[A-Z]{1}[A-Za-z0-9]{1}",
      "check_digit_regex": "[0-9][0-9]",
      "code": "BR",
      "country": "Brazil",
      "size": 29
    },
    "description": "IBAN passed validation",
    "iban": "BR1800000000141455123924100C2",
    "is_valid": true
  }
  ```
  
  
  ## Project description
  
  Main motivation for creating this project was study and self development in the subjects
  of [Deep Learning](https://en.wikipedia.org/wiki/Deep_learning)
  and [Artificial Neural Networks](https://en.wikipedia.org/wiki/Artificial_neural_network)
  using [Tensorflow](https://www.tensorflow.org), a popular Machine Learning Platform.
  
  Considering the Artificial Intelligence domain landscape in the year of 2022, several Machine Learning SaaS and PaaS
  offers available in the market in a field of computer science that just had become a mainstream topic. It just made
  sense to me picking one major framework and start practicing with a well known problem such as IBAN validation.
  
  As a software engineer, with this project I had found answers to some of my practical questions and was rewarded with
  proficiency in modeling neural networks and distributing them for prediction at scale using cloud containers.
  
  ### The challenge
  
  Looking for an idea for a hands-on/short-lived project to practice and learn Neural Network modelling
  with [Keras](https://keras.io/api/) and [TensorFlow](https://www.tensorflow.org/), I came across this idea of creating
  this [IBAN](https://www.iso13616.org) validator as this is a simple use case with good references over the internet.
  
  ### The proposed solution
  
  In order to employ a simple yet efficient Machine Learning Model, the proposed solution
  addresses the challenge using the following approach.
  
  > 1. The Machine Learning Model should memorize [a table](](https://github.com/bsantanna/iban-validator-model/blob/main/modules/training/data/country_validation_json.csv)) with country
       specific [Regular Expression](https://en.wikipedia.org/wiki/Regular_expression) rules formatted as static JSON
       document strings.
  > 2. Predict the correct JSON when other items from the table are given as features, extracted from the
       input [IBAN](https://www.iso1