Skip to content

Commit

Permalink
readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
@kmaphoenix
kmaphoenix committed Feb 9, 2023
1 parent 2e84c76 commit 87be324
Showing 1 changed file with 87 additions and 18 deletions.
105 changes: 87 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,87 @@ With DFCX SCRAPI you can perform many bot building and maintenance actions at sc
- Extract Change History information
- Search across all Flows/Pages/Routes to find a specific parameter or utterance using Search Util functions
- Quickly move CX resources between agents using Copy Util functions!
- Build the fundamental protobuf objects that CX uses for each resource type using Maker/Builder Util functions
- Build the fundamental protobuf objects that CX uses for each resource type using Builder methods
- ...and much, much more!

## Built With
* Python 3.8+


<!-- AUTHENTICATION -->
# Authentication
Authentication can vary depending on how and where you are interacting with SCRAPI.

## Google Colab
If you're using SCRAPI with a [Google Colab](https://colab.research.google.com/) notebook, you can add the following to the top of your notebook for easy authentication:
```py
project_id = '<YOUR_GCP_PROJECT_ID>'

# this will launch an interactive prompt that allows you to auth with GCP in a browser
!gcloud auth application-default login --no-launch-browser

# this will set your active project to the `project_id` above
!gcloud auth application-default set-quota-project $project_id
```

After running the above, Colab will pick up your credentials from the environment and pass them to SCRAPI directly. No need to use Service Account keys!
You can then use SCRAPI simply like this:
```py
from dfcx_scrapi.core.intents import Intents

agent_id = '<YOUR_AGENT_ID>'
i = Intents() # <-- Creds will be automatically picked up from the environment
intents_map = i.get_intents_map(agent_id)
```
---
## Cloud Functions / Cloud Run
If you're using SCRAPI with [Cloud Functions](https://cloud.google.com/functions) or [Cloud Run](https://cloud.google.com/run), SCRAPI can pick up on the default environment creds used by these services without any additional configuration!

1. Add `dfcx-scrapi` to your `requirements.txt` file
2. Ensure the Cloud Function / Cloud Run service account has the appropriate Dialogflow IAM Role

Once you are setup with the above, your function code can be used easily like this:
```py
from dfcx_scrapi.core.intents import Intents

agent_id = '<YOUR_AGENT_ID>'
i = Intents() # <-- Creds will be automatically picked up from the environment
intents_map = i.get_intents_map(agent_id)
```

---
## Local Python Environment
Similar to Cloud Functions / Cloud Run, SCRAPI can pick up on your local authentication creds _if you are using the gcloud CLI._

1. Install [gcloud CLI](https://cloud.google.com/sdk/docs/install).
2. Run `gcloud init`.
3. Run `gcloud auth login`
4. Run `gcloud auth list` to ensure your principal account is active.

This will authenticate your principal GCP account with the gcloud CLI, and SCRAPI can pick up the creds from here.

---
## Exceptions and Misc.
There are some classes in SCRAPI which still rely on Service Account Keys, notably the [DataframeFunctions](https://github.com/GoogleCloudPlatform/dfcx-scrapi/blob/main/src/dfcx_scrapi/tools/dataframe_functions.py) class due to how it authenticates with Google Sheets.

In order to use these functions, you will need a Service Account that has appropriate access to your GCP project.
For more information and to view the official documentation for service accounts go to [Creating and Managing GCP Service Accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts).

Once you've obtained a Service Account Key with appropriate permissions, you can use it as follows:
```py
from dfcx_scrapi.core.intents import Intents
from dfcx_scrapi.tools.dataframe_functions import DataframeFunctions

agent_id = '<YOUR_AGENT_ID>'
creds_path = '<PATH_TO_YOUR_SERVICE_ACCOUNT_JSON_FILE>'

i = Intents(creds_path=creds_path)
dffx = DataframeFunctions(creds_path=creds_path)

df = i.bulk_intent_to_df(agent_id)
dffx.dataframe_to_sheets('GOOGLE_SHEET_NAME', 'TAB_NAME', df)
```

<!-- GETTING STARTED -->
# Getting Started
## Environment Setup
Expand All @@ -82,12 +157,7 @@ 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 and to view the official documentation for service accounts go to [Creating and Managing GCP Service Accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts).

<!-- USAGE EXAMPLES -->
# Usage
## 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
Expand All @@ -108,19 +178,13 @@ i = Intents(creds_path, agent_id=agent_path)
df = i.bulk_intent_to_df()
```

_For more examples, please refer to [Examples](/examples) or [Tools](/src/dfcx_scrapi/tools)._

# Library Composition
Here is a brief overview of the SCRAPI library's structure and the motivation behind that structure.

## Core
The [Core](/src/dfcx_scrapi/core) folder is synonymous with the core Resource types in the DFCX Agents like:
- agents
- intents
- entity_types
- etc.

The [Core](/src/dfcx_scrapi/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.
The [Core](/src/dfcx_scrapi/core) folder is synonymous with the core Resource types in the DFCX Agents (agents, intents, flows, etc.)
* This folder contains the high level building blocks of SCRAPI
* These classes and methods can be used to build higher level methods or custom tools and applications

## Tools
The [Tools](/src/dfcx_scrapi/tools) folder contains various customized toolkits that allow you to do more complex bot management tasks, such as
Expand All @@ -129,6 +193,12 @@ The [Tools](/src/dfcx_scrapi/tools) folder contains various customized toolkits
- Move data to and from DFCX and other GCP Services like BigQuery, Sheets, etc.
- Create customized search queries inside of your agent resources

## Builders
The [Builders](/src/dfcx_scrapi/builders) folder contains simple methods for constructing the underlying protos in Dialogflow CX
- Proto objects are the fundamental building blocks of Dialogflow CX
- Builder classes allow the user to construct Dialogflow CX resource _offline_ without any API calls
- Once the resource components are constructed, they can then be pushed to a live Dialogflow CX agent via API

<!-- CONTRIBUTING -->
# Contributing
We welcome any contributions or feature requests you would like to submit!
Expand All @@ -146,8 +216,7 @@ Distributed under the Apache 2.0 License. See [LICENSE](LICENSE.txt) for more in
<!-- CONTACT -->
# Contact
Patrick Marlow - [email protected] - [@kmaphoenix](https://github.com/kmaphoenix)
David "DC" Collier - [email protected] - [@DCsan](https://github.com/dcsan)
Lauren Greenford - [email protected] - [@Greenford](https://github.com/Greenford)
Milad Tabrizi - [email protected] - [@MRyderOC](https://github.com/MRyderOC)

Project Link: [https://github.com/GoogleCloudPlatform/dfcx-scrapi](https://github.com/GoogleCloudPlatform/dfcx-scrapi)

Expand Down

0 comments on commit 87be324

Please sign in to comment.