<commit_before>Caek: an experiment in modular situational computation
======================================================

Caek is an experiment that aims to make mobile computers such as phones and
tablets feel smarter to their users by trying to understand input and provide
appropriate actions. It is built to be extended by developing and installing
third-party modules that can specialize in contexts such as social networks or
ubiquitous capture.

The current functionality is similar to the experience of [Just
Type](https://developer.palm.com/content/api/dev-guide/mojo/just-type.html), but
I hope to expand it to be a bit more powerful (see Modules, below).

## Modules

Modules are independently packaged services that you can install to extend Caek.
They respond to content queries such as text, images (coming soon), and videos
(also coming soon) with actions that are (hopefully) appropriate to what you are
trying to do.

There are only a few modules that come packaged with Caek. They are extremely
basic and not very smart at all, but they should provide minimum viable
functionality.

* **Launcher**: matches text with the names of installed apps.
* **Contacts**: matches text with contacts in your device.
* **Email**: recognizes email addresses.
* **Phone**: recognizes phone numbers.
* **Search**: provides an action for performing a search.
* **Browser**: recognizes URIs.

***Modules are disabled by default.*** You must enable modules before they will
become active, because (1) Caek currently has no way of knowing when you install
a new module, and (2) because modules enabling themselves opens you up to all
sorts of unscrupulous spying code being run without your knowledge (note to
developers: don't spy on people; that's evil).

To enable modules, start Caek and select "Manage modules" from the overflow menu
in the action bar. Scroll down to the module that you want to enable and toggle
the switch to "ON", then press Back or the Up affordance to return to Caek. The
module should start receiving your input immediately after you enable it.

## Building and installing Caek

Caek can be built with just the [Android
SDK](http://developer.android.com/sdk/index.html), for API level 18. **Caek
requires a minimum API level of 14 because I don't want to deal with
compatibility issues right now.**

    git clone https://github.com/ayshen/caek
    cd caek
    android update project --path .
    ant clean && ant debug

## Developing modules

Modules are simple subclasses of
[`Service`](http://developer.android.com/reference/android/app/Service.html).
To make your own module (we'll call it `MyModule`), you should follow the format
shown here:

    // Module is a class in this project.
    // IModule is an AIDL interface in this project; IModule.Stub is
    // automatically generated by AIDL as part of building the project.
    public class MyModule extends Module
    {
        @Override
        public android.os.IBinder createBinder()
        {
            return new IModule.Stub()
            {
                public java.util.List<android.content.Intent> process(
                        android.content.Intent data)
                {
                    // ...
                    // Make sure you return a List! If you decline to respond,
                    // return an empty List instead!
                }
            };
        }
    }

Content queries are given to your module as extras in the
[`Intent`](http://developer.android.com/reference/android/content/Intent.html)
`data`.

* Text queries are Strings under the key `Module.QUERY_TEXT`.
* Audio queries are not yet implemented.
* Image queries are not yet implemented.
* Video queries are not yet implemented.

Your module is expected to return a
[`List`](http://developer.android.com/reference/java/util/List.html) of `Intent`
objects, each of which should be ready to be passed ***without modification***
into
[`Context.startActivity()`](http://developer.android.com/reference/android/content/Context.html#startActivity%28android.content.Intent%29).
Each response `Intent` will be displayed as a short text item and (coming soon)
a small (48dp square or smaller) icon.

* The label should be attached to the `Intent` as a `String` extra under the key
  `Module.RESPONSE_TEXT`.
* The icon should be attached as a
  [`Bitmap`](http://developer.android.com/reference/android/grpahics/Bitmap.html)
  under the key `Module.RESPONSE_THUMBNAIL`. It isn't used right now, but it
  may show up in a future commit.

Your module is also a
[`Service`](http://developer.android.com/reference/android/app/Service.html), so
you can do anything that a service can do, such as writing to your
[`SharedPreferences`](http://developer.android.com/reference/android/content/SharedPreferences.html),
performing file I/O, reading the hardware sensors, etc. This should make it easy
to implement things like context-awareness and interaction history.

## Why "Caek"?

Using modules to build an AI reminded me of GLaDOS from
[Portal](http://store.steampowered.com/app/400) (hence the package name for this
project). The intelligence modules that attach to Caek sort of act like the
[Aperture Science Artificial Personality
Constructs](http://theportalwiki.com/wiki/Cores), one of which (the "Cake Core")
is preoccupied with cake.
<commit_msg>Oops.<commit_after>Caek: an experiment in modular situational computation
======================================================

Caek is an experiment that aims to make mobile computers such as phones and
tablets feel smarter to their users by trying to understand input and provide
appropriate actions. It is built to be extended by developing and installing
third-party modules that can specialize in contexts such as social networks or
ubiquitous capture.

The current functionality is similar to the experience of [Just
Type](https://developer.palm.com/content/api/dev-guide/mojo/just-type.html), but
I hope to expand it to be a bit more powerful (see Modules, below).

## Modules

Modules are independently packaged services that you can install to extend Caek.
They respond to content queries such as text, images (coming soon), and videos
(also coming soon) with actions that are (hopefully) appropriate to what you are
trying to do.

There are only a few modules that come packaged with Caek. They are extremely
basic and not very smart at all, but they should provide minimum viable
functionality.

* **Launcher**: matches text with the names of installed apps.
* **Contacts**: matches text with contacts in your device.
* **Email**: recognizes email addresses.
* **Phone**: recognizes phone numbers.
* **Search**: provides an action for performing a search.
* **Browser**: recognizes URIs.

***Modules are disabled by default.*** You must enable modules before they will
become active, because (1) Caek currently has no way of knowing when you install
a new module, and (2) because modules enabling themselves opens you up to all
sorts of unscrupulous spying code being run without your knowledge (note to
developers: don't spy on people; that's evil).

To enable modules, start Caek and select "Manage modules" from the overflow menu
in the action bar. Scroll down to the module that you want to enable and toggle
the switch to "ON", then press Back or the Up affordance to return to Caek. The
module should start receiving your input immediately after you enable it.

## Building and installing Caek

Caek can be built with just the [Android
SDK](http://developer.android.com/sdk/index.html), for API level 18. **Caek
requires a minimum API level of 14 because I don't want to deal with
compatibility issues right now.**

    git clone https://github.com/ayshen/caek
    cd caek
    android update project --path .
    ant clean && ant debug

## Developing modules

Modules are simple subclasses of
[`Service`](http://developer.android.com/reference/android/app/Service.html).
To make your own module (we'll call it `MyModule`), you should follow the format
shown here:

    // Module is a class in this project.
    // IModule is an AIDL interface in this project; IModule.Stub is
    // automatically generated by AIDL as part of building the project.
    public class MyModule extends Module
    {
        @Override
        public android.os.IBinder createBinder()
        {
            return new IModule.Stub()
            {
                public java.util.List<android.content.Intent> process(
                        android.content.Intent data)
                {
                    // ...
                    // Make sure you return a List! If you decline to respond,
                    // return an empty List instead!
                }
            };
        }
    }

Content queries are given to your module as extras in the
[`Intent`](http://developer.android.com/reference/android/content/Intent.html)
`data`.

* Text queries are `String`s under the key `Module.QUERY_TEXT`.
* Audio queries are not yet implemented.
* Image queries are not yet implemented.
* Video queries are not yet implemented.

Your module is expected to return a
[`List`](http://developer.android.com/reference/java/util/List.html) of `Intent`
objects, each of which should be ready to be passed ***without modification***
into
[`Context.startActivity()`](http://developer.android.com/reference/android/content/Context.html#startActivity%28android.content.Intent%29).
Each response `Intent` will be displayed as a short text item and (coming soon)
a small (48dp square or smaller) icon.

* The label should be attached to the `Intent` as a `String` extra under the key
  `Module.RESPONSE_TEXT`.
* The icon should be attached as a
  [`Bitmap`](http://developer.android.com/reference/android/grpahics/Bitmap.html)
  under the key `Module.RESPONSE_THUMBNAIL`. It isn't used right now, but it
  may show up in a future commit.

Your module is also a
[`Service`](http://developer.android.com/reference/android/app/Service.html), so
you can do anything that a service can do, such as writing to your
[`SharedPreferences`](http://developer.android.com/reference/android/content/SharedPreferences.html),
performing file I/O, reading the hardware sensors, etc. This should make it easy
to implement things like context-awareness and interaction history.

## Why "Caek"?

Using modules to build an AI reminded me of GLaDOS from
[Portal](http://store.steampowered.com/app/400) (hence the package name for this
project). The intelligence modules that attach to Caek sort of act like the
[Aperture Science Artificial Personality
Constructs](http://theportalwiki.com/wiki/Cores), one of which (the "Cake Core")
is preoccupied with cake.

{'fraction_non_alphanumeric': 0.08907452599962455, 'fraction_numerical': 0.002815843814529754, 'mean_word_length': 3.7021182700794353, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2416764', 'n_tokens_mistral': 2822, 'n_tokens_neox': 2709, 'n_words': 1314}