diff --git a/.gitignore b/.gitignore index 57bfb20..709c78d 100644 --- a/.gitignore +++ b/.gitignore @@ -13,4 +13,5 @@ pip-selfcheck.json __pycache__/ dump.rdb .vs/ -*-credentials.json \ No newline at end of file +*-credentials.json +report.json diff --git a/README.md b/README.md index ccd67ae..e57af17 100644 --- a/README.md +++ b/README.md @@ -13,17 +13,17 @@ Who The Hill is an MMS-based facial recognition service for members of Congress. Who The Hill in the flesh ## Local Installation -Before getting the app running, you'll need a [Twilio](https://www.twilio.com/) account (with an operational MMS number), an [Amazon Rekognition](https://aws.amazon.com/rekognition/) account, an [Amazon SES](https://aws.amazon.com/ses) account, and an [Amazon S3](https://aws.amazon.com/s3) or [Google Cloud Storage](https://cloud.google.com/storage/) account +Before getting the app running, you'll need a [Twilio](https://www.twilio.com/) account (with an operational MMS number), an [Amazon Rekognition](https://aws.amazon.com/rekognition/) account and an [Amazon S3](https://aws.amazon.com/s3) or [Google Cloud Storage](https://cloud.google.com/storage/) account. + +Who The Hill also requires Python3 and works best with `virtualenv` and `virtualenvwrapper`. For more on how NYT Interactive News sets up our Python environment, check out [this blog post by Sara Simon](https://open.nytimes.com/set-up-your-mac-like-an-interactive-news-developer-bb8d2c4097e5). ``` -git clone https://github.com/newsdev/who_the_hill.git -cd who_the_hill -virtualenv -p /path/to/Python3 . -. bin/activate +git clone https://github.com/newsdev/who-the-hill.git && cd who-the-hill +mkvirtualenv whothehill pip install -r requirements.txt ``` -To run the app locally, you will need some environment variables... +To run the app locally, you will need some environment variables. Three sets of AWS (or AWS-like) keys are needed: * AWS Rekognition credentials @@ -40,11 +40,6 @@ AWS_GCS_ACCESS_KEY_ID AWS_GCS_SECRET_ACCESS_KEY ``` -* AWS SES credentials (for email alerter) -``` -AWS_ACCESS_KEY_ID_EMAIL -AWS_SECRET_ACCESS_KEY_EMAIL -``` (You can find more information about the AWS and AWS-like credentials [here.](http://boto3.readthedocs.io/en/latest/guide/configuration.html#environment-variable-configuration)) You will also need credentials and a number from [Twilio.](https://www.twilio.com/): @@ -54,22 +49,11 @@ TWILIO_AUTH_TOKEN TWILIO_NUMBER ``` -You'll also need to have somewhere to send spam email alerts and an email account from which to send them: -``` -EMAIL_RECIPIENTS -EMAIL_SENDER -``` - To check whether results returned from Rekognition are actually members of Congress, you can either use the json dump of members of Congress (as well as variations on spellings of their name) included in this repo, or use your own API endpoint that returns similarly formatted json. If you don't set this environment variable, Who The Hill will default to using the included json file: ``` NICKNAMES_ENDPOINT ``` -Finally, you'll also have to decide what the public facing name of your app will be. We like "Who The Hill," but apparently some people aren't so keen on that name: -``` -APP_NAME -``` - You can store your environment variables in a `dev.env` file... ``` export AWS_ACCESS_KEY_ID='' @@ -83,13 +67,21 @@ export TWILIO_AUTH_TOKEN='' ...and run `source dev.env`. This will export your credentials to your environment. ## Running the App -Running the app locally requires running two servers at the same time: one for app.py (which houses the call to Amazon's Rekognition) and another for twilio_app.py (which handles receiving and sending messages via Twilio). +You can run the app locally as a web service that integrates with Twilio or as a CLI for examining a folder full of images to recognize. -One method for running the application uses [ngrok](https://ngrok.com/) to tunnel to localhost, providing a public URL for the Twilio webhook. Ngrok allows you to expose the Twilio server so it can receive text messages. That public link refreshes every time the ngrok server is shut down. +### As a web application +Run the app locally `python who_the_hill/web/pub.py` and tunnel with [ngrok](https://ngrok.com/) so that you can integrate with Twilio, which needs a public-facing endpoint to POST data to. -## Acknowledgements -This app was developed by Interactive News interns [Gautam Hathi](https://github.com/gautamh) and [Sherman Hewitt](https://github.com/SHewitt95). +### As a CLI for recognition +Put the images within which you'd like to recognize members of Congress into a folder like `/tmp/to_recognize` and then call the CLI like this: -The idea was pitched by [Rachel Shorey](https://github.com/rshorey) and [Jeremy Bowers](https://github.com/jeremyjbowers). +``` +python who_the_hill/cli --directory /tmp/to_recognize/ +``` + +The app will examine the images, find and recognize faces, and produce a JSON report. Note: The CLI still requires working S3/GCS tokens and (obviously) access to the AWS Rekognition API. It does not require Twilio credentials, though. + +## Acknowledgements +[Jennifer Steinhauer](https://www.nytimes.com/by/jennifer-steinhauer) came up with the original idea behind Who The Hill and was an enthusiastic sponsor and tester. -The idea was conceived by [Jennifer Steinhauer](https://www.nytimes.com/by/jennifer-steinhauer). +Who The Hill was developed by Interactive News interns [Gautam Hathi](https://github.com/gautamh) and [Sherman Hewitt](https://github.com/SHewitt95) in the summer of 2017 and partially rewritten in the spring of 2018 by [Jeremy Bowers](https://github.com/jeremyjbowers), all under the watchful eye of [Rachel Shorey](https://github.com/rshorey). \ No newline at end of file