Merge pull request #16 from PAIR-code/iislucas-improve-readme

docs: improve main README with what this library supports

Author: iislucas

README.md

@@ -4,34 +4,46 @@
 [![npm latest version](https://img.shields.io/npm/v/ts-llmt/latest.svg)](https://www.npmjs.com/package/ts-llmt)
 
 This repository holds experimental code aimed at providing native TypeScript
-support for Large Language Model Templates. The key idea being explored is that
-templates have a type that corresponds to the names of the variables within the
-template.
+support for Large Language Model Templates.
 
-For example:
+The key idea is to track "named-holes" in templates at type-checking (typing)
+time. This means:
+
+- You never need to debug an accidental substitution for the wrong variable name.
+- You can substitute for some variables but not others, in any order you like, and the remaining
+  variables are tracked in the type.
+- You can substitute templates with more holes into a named-hole in a template, and you get the
+  correct remaining holes in the right places in the final template.
+- The same hole can appear in multiple places, substitution substitutes it everywhere, as you would
+  expect.
+- There is support for few-shot prompts (where you have some iterated sub-template over a data
+  structure).
+
+Here's a mini-example:
 
 ```ts
 import { nv, template } from 'ts-llmt';
 
 const thingVar = nv('thing');
 const thing2Var = nv('thing2');
-// The type of `whatIsAtoB` is inferred to be `Template<"thing" | "thing2">`
+// *NOTE*: type of `whatIsAtoB` is magically inferred to be:
+//         `Template<"thing" | "thing2">`
 const whatIsAtoB = template`what is a ${thingVar} to a ${thing2Var}?`;
 
-// Replacing the thing variable give type:  `Template<"thing2">`
+// Replacing the `thing` variable in whatIsAtoB, gives the type:
+//         `Template<"thing2">`
 const whatIsTabletoB = whatIsAtoB.vars.thing.substStr('table');
 
 // The escaped raw form of this template is as so:
 expect(whatIsTabletoB.escaped).toEqual('what is a table to a {{thing2}}?');
 ```
 
-A nice feature of this is that you get as "as-you-type" error checking, and
-arguments can be auto-completed by the IDE. e.g. you can directly reference the
-variables from the 'vars' parameter of a template, and anything else is an
-as-you-type error in your editor.
+The key nice feature of this is that you get _as "as-you-type" error checking_,
+and _arguments can be auto-completed by the IDE_. You can never substitute for a
+variable that is not there.
 
-You can do multi-variable replacement nicely, and still have all the wonderful
-type-checking like so:
+You can do multi-variable replacement nicely too, and still have all the
+wonderful type-checking like so:
 
 ```ts
 whatIsAtoB.substs({ thing: 'table', thing2: 'chair' });