Python Dialogflow CX Scripting API (SCRAPI)

A high level scripting API for bot builders, developers, and maintainers.

Introduction

The Python Dialogflow CX Scripting API (DFCX SCRAPI) is a high level API that extends the official Google Python Client for Dialogflow CX which makes using CX easier, more friendly, and more pythonic for bot builders, developers and maintainers.

SCRAPI --> Python Dialogflow CX
as
Keras --> Tensorflow

What Can I Do With DFCX SCRAPI?

With DFCX SCRAPI, you can perform many bot building and maintenance actions at scale including, but not limited to:

  • Create, Update, Delete, Get, List for all CX resources types (i.e. Intents, Entity Types, Pages, Flows, etc.)
  • Convert commonly accessed CX Resources to Pandas Dataframes for data manipulation and analysis
  • Ex: bulk_intents_to_dataframe provides you all intents and training phrases in a Pandas DataFrame that can be manipulated and/or exported to CSV or back to CX
  • Have fully automated conversations with a CX agent (powerful for regression testing!)
  • Extract Validation information to assist in tuning your agent NLU, routes, etc.
  • Extract Change History information to assist with Change Management and Accountability for your devlepment team
  • Search Util functions to look across all Flows/Pages/Routes to find a specific parameter or utterance you need to locate
  • Copy Util functions that allow you to quickly move CX resource between agents!
  • Ex: copy_intent_to_agent allows you to choose source and destination Agent IDs and a human readable Intent Display Name and BAM! Intent is moved with all training phrases to the destination agent!
  • Maker/Builder Util functions that allow you to build the fundamental protobuf objects that CX uses for each resource type
  • Ex: if you want to build a new Intent (or hundreds!) with training phrases from a pandas dataframe, you can build them all offline/in memory using the build_intent method
  • ...and much, much more!

Built With

  • Python 3.8+

Getting Started

Environment Setup

Set up Google Cloud Platform credentials and install dependencies.

gcloud auth login
gcloud auth application-default login
gcloud config set project <project name>

python3 -m venv venv
source ./venv/bin/activate
pip install -r requirements.txt

Authentication

In order to use the functions and API calls to Dialogflow CX, you will need a Service Account that has appropriate access to your GCP project.
For more information on view the official docs for Creating and Managing GCP Service Accounts.

Usage

To run a simple bit of code you can do the following:

  • Import a Class from dfcx_scrapi.core
  • Assign your Service Account to a local variable
from dfcx_scrapi.core.intents import Intents

creds_path = '<PATH_TO_YOUR_SERVICE_ACCOUNT_JSON_FILE>'
agent_path = '<FULL_DFCX_AGENT_ID_PATH>'

# DFCX Agent ID paths are in this format:
# 'projects/<project_id>/locations/<location_id>/agents/<agent_id>'

# Instantiate your class object and pass in your credentials
i = Intents(creds_path, agent_id=agent_path)

# Retrieve all Intents and Training Phrases from an Agent and push to a Pandas DataFrame
df = i.bulk_intent_to_df()

For more examples, please refer to Examples or Tools.

Library Composition

A brief overview of the motivation behind the library structure

Core

The Core folder is synonymous with the core Resource types in the DFCX Agents like:

  • agents
  • intents
  • entity_types
  • etc.

The Core folder is meant to contain the fundamental building blocks for even higher level customized tools and applications that can be built with this library.

Tools

The Tools folder contains various customized toolkits that allow you to do more complex bot management tasks.
These include things like:

  • Manipulating Agent Resource types into various DataFrame structure for data scienc-y type tasks
  • Copying Agent Resources between Agents and GCP Projects on a resource by resource level
  • Moving data to and from DFCX and other GCP Services like BigQuery, Sheets, etc.
  • Creating customized search queries inside of your agent resources
  • i.e. - Find all parameters in all pages in the agent that contain the string dtmf

Roadmap

TBD

Contributing

We welcome any contributions or feature requests you would like to submit!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Contact

Patrick Marlow - [email protected]  - @kmaphoenix
David "DC" Collier - [email protected]  - @DCsan
Henry Drescher - [email protected]  - @Hgithubacct

Project Link: https://github.com/GoogleCloudPlatform/dfcx-scrapi

Acknowledgements

Dialogflow CX Python Client Library

GitHub - GoogleCloudPlatform/dfcx-scrapi: A high level scripting API for bot builders, developers, and maintainers.
A high level scripting API for bot builders, developers, and maintainers. - GitHub - GoogleCloudPlatform/dfcx-scrapi: A high level scripting API for bot builders, developers, and maintainers.
GitHubGoogleCloudPlatform