first

README.md

@@ -1,3 +1,23 @@
-# perry
+# Perry
 
-A small agent.  It doesn't do much.  But somehow it does everything that is necessary to get the job done.
+Perry is a small utility for working with persistent conversational agents.
+
+It grew out of Chat2. Perry is not a scheduler, artifact graph, translation pipeline, or full-featured agent framework. Applications own why work happens and what the work means. Perry owns the conversational agent mechanics around a local model.
+
+Current API:
+
+- `warmUp()`
+- `prepare(name, systemPrompt, segments)`
+- `ask(agent, input, options)`
+- `followUp(agent, originalInput, previousReply, input, options)`
+- `model()`
+
+Current backend: LM Studio Responses API. The extracted source contained no active Ollama backend, so none was resurrected.
+
+## Repetition self-destruct
+
+Perry watches reasoning and final-content streams independently for exact contiguous periodic repetition. If the tail becomes the same token sequence repeated seven complete times with no novel tokens between repetitions, Perry aborts that response and raises a retryable `PERRY_REPETITION_LOOP` error.
+
+The detector is deliberately literal. Similar ideas with changing token sequences are allowed to continue; Perry intervenes only after the stream locks into an exact repeated orbit. Pattern periods from one through 256 tokens are checked.
+
+The normal retry layer then starts the response again without appending the pathological partial response to the conversation.