add trace logging and type hinting