imprint-layer 0.3.0__tar.gz

imprint_layer-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabe Hernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imprint_layer-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md
+recursive-include examples *.py *.json
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]

imprint_layer-0.3.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: imprint-layer
+Version: 0.3.0
+Summary: A personality calibration layer for any chat model: learns how one user wants an assistant to talk, from their own messages.
+License-Expression: MIT
+Keywords: llm,personalization,system-prompt,assistant,embeddings
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: minilm
+Requires-Dist: sentence-transformers>=2.2; extra == "minilm"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# Imprint
+
+**Tell your bot to be wittier. It becomes wittier.**
+
+A personality calibration layer for any chat model. Imprint learns how one person wants an assistant to talk from that person's own messages. It then renders a short plain-text block that you put in the system prompt.
+
+```python
+from imprint import Imprint
+
+imp = Imprint("me.profile.json")
+
+def on_user_message(text, sent_at):
+    imp.learn(text, timestamp=sent_at)       # learn first...
+    system = BASE_PROMPT + "\n\n" + imp.directive()   # ...then build the prompt
+    return call_your_model(system, history)
+```
+
+## What it learns
+
+**Eight dials, each a value from 0 to 1:**
+
+| Dial | Low ↔ high |
+|---|---|
+| verbosity | concise ↔ detailed |
+| autonomy | ask first ↔ act on own judgment |
+| formality | casual ↔ formal |
+| proactivity | wait for instructions ↔ suggest next steps |
+| riskTolerance | careful claims ↔ committed takes |
+| humor | earnest ↔ dry, sarcastic wit |
+| warmth | matter-of-fact ↔ emotionally present |
+| flirt | platonic ↔ playful romantic charge |
+
+The model never sees the numbers. Each dial has a few bands, and the directive carries one plain sentence per dial for the band it's in. Use `Imprint(traits=[...])` to learn and inject only the dials you want. A work assistant would probably drop `flirt`.
+
+**Dials move three ways:**
+
+- **Direct steering.** "be wittier", "more sarcastic", "less detail please", "you're too formal", "dial up the warmth", "no more snark". The named dial moves one full band, so the very next reply changes. Saying it again moves one more band.
+  - Questions about a dial ("why so sarcastic?") don't steer.
+  - Passing mentions don't steer, and neither does talk about other people ("my boss could be funnier").
+  - Praise never steers down: "you're too kind" is a compliment.
+  - A command you take back in the same message ("be wittier. actually, never mind") is cancelled.
+- **Tone of feedback.** Messages like "you're repeating yourself, too much filler" nudge a dial a little. Each message's embedding is compared against example phrases for each end of each dial. Ordinary conversation stays under the thresholds and moves nothing.
+- **Standing rules, captured in two tiers.** Nobody has to learn a syntax.
+  - *Explicit forms* become rules immediately: "never use emoji", "always: cite sources", "from now on, use metric units", "remember: I'm vegetarian".
+  - *Natural preference statements* become candidate rules: "I prefer metric units", "I hate it when you use bullet points". A candidate becomes a rule only when the user says the same thing again in a different message at least an hour later. Candidates are never injected, and they expire after 90 days without corroboration.
+  - Neither tier stores one-off tasks. A deadline, a named recipient, "now", or "this one" marks a task, not a preference ("always send the report to Dana by Friday" is a task).
+
+## Model-agnostic, with an honest caveat
+
+Imprint never calls a chat model. It works with anything that accepts a system prompt: a local model behind llama.cpp, Ollama or vLLM, or a hosted frontier model through its API. The default embedder (`all-MiniLM-L6-v2`) runs locally on CPU, so the user's messages aren't sent anywhere for learning.
+
+**The mechanism is model-agnostic. The effect is not.** How closely replies follow the calibration block depends on how well the host model follows instructions. A strong model will follow "Dry wit and occasional sarcasm are welcome" closely. A small model may follow it loosely, or not at all.
+
+## Integration contract
+
+Your host provides two things:
+
+1. **Each user message, with the time the user sent it.** Call `learn(text, timestamp=...)` before you build the prompt for that turn. Without a timestamp, Imprint still learns, but it records the time as unknown (never the processing time), skips confidence decay, and can't corroborate candidate rules. It logs a warning when this happens.
+2. **A place to inject text into the system prompt.** `directive()` returns the block, or `""` until `warmup` interactions (default 5) have passed. It stays identical byte for byte until something is actually learned, so it works with prompt caching.
+
+Everything beyond that is up to the host: memory, retrieval, tools, scheduling.
+
+## Install
+
+```bash
+pip install imprint-layer
+```
+
+The distribution is `imprint-layer`; the import is `imprint`. The default local embedder needs sentence-transformers: `pip install "imprint-layer[minilm]"`. Without it, pass your own embedder.
+
+A custom embedder is any object with a `name` and `embed(list_of_texts) -> array of shape (n, d)`. Pass it as `Imprint(..., embedder=MyEmbedder())`.
+
+## Examples
+
+- `examples/local_chat.py`: a chat loop against a local OpenAI-compatible server.
+- `examples/frontier_api.py`: the same injection, against a hosted API.
+
+Both are reference integrations to read and adapt. They aren't products.
+
+## Dashboard
+
+```bash
+imprint-dashboard my.profile.json -o dashboard.html
+```
+
+This renders a read-only static page: each dial's value and band, the standing rules, candidate rules and observation counts. Try it on `examples/sample.profile.json`.
+
+## Privacy
+
+A profile is personal data. It records how one person talks and what they've asked for. Keep profiles on the user's machine or in your own storage, and **never commit a real profile**. The included `.gitignore` excludes `*.profile.json`. Observations store short excerpts of the messages that moved a dial, and candidate rules store the user's own sentence.
+
+## What Imprint is not
+
+- Not a memory system. It doesn't store facts about the user or conversation history.
+- Not a hosted service. There's no account or server, and no data leaves your machine except through the chat calls you make yourself.
+- Not fine-tuning. Nothing about the model changes; Imprint only adds prompt text.
+- Not a safety layer. The calibration block is a preference, and your model's own policies still apply.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest                                   # deterministic fake embedder, no downloads
+IMPRINT_TEST_MINILM=1 pytest             # also run the real-embedder checks
+```
+
+## License
+
+MIT

imprint_layer-0.3.0/README.md

@@ -0,0 +1,109 @@
+# Imprint
+
+**Tell your bot to be wittier. It becomes wittier.**
+
+A personality calibration layer for any chat model. Imprint learns how one person wants an assistant to talk from that person's own messages. It then renders a short plain-text block that you put in the system prompt.
+
+```python
+from imprint import Imprint
+
+imp = Imprint("me.profile.json")
+
+def on_user_message(text, sent_at):
+    imp.learn(text, timestamp=sent_at)       # learn first...
+    system = BASE_PROMPT + "\n\n" + imp.directive()   # ...then build the prompt
+    return call_your_model(system, history)
+```
+
+## What it learns
+
+**Eight dials, each a value from 0 to 1:**
+
+| Dial | Low ↔ high |
+|---|---|
+| verbosity | concise ↔ detailed |
+| autonomy | ask first ↔ act on own judgment |
+| formality | casual ↔ formal |
+| proactivity | wait for instructions ↔ suggest next steps |
+| riskTolerance | careful claims ↔ committed takes |
+| humor | earnest ↔ dry, sarcastic wit |
+| warmth | matter-of-fact ↔ emotionally present |
+| flirt | platonic ↔ playful romantic charge |
+
+The model never sees the numbers. Each dial has a few bands, and the directive carries one plain sentence per dial for the band it's in. Use `Imprint(traits=[...])` to learn and inject only the dials you want. A work assistant would probably drop `flirt`.
+
+**Dials move three ways:**
+
+- **Direct steering.** "be wittier", "more sarcastic", "less detail please", "you're too formal", "dial up the warmth", "no more snark". The named dial moves one full band, so the very next reply changes. Saying it again moves one more band.
+  - Questions about a dial ("why so sarcastic?") don't steer.
+  - Passing mentions don't steer, and neither does talk about other people ("my boss could be funnier").
+  - Praise never steers down: "you're too kind" is a compliment.
+  - A command you take back in the same message ("be wittier. actually, never mind") is cancelled.
+- **Tone of feedback.** Messages like "you're repeating yourself, too much filler" nudge a dial a little. Each message's embedding is compared against example phrases for each end of each dial. Ordinary conversation stays under the thresholds and moves nothing.
+- **Standing rules, captured in two tiers.** Nobody has to learn a syntax.
+  - *Explicit forms* become rules immediately: "never use emoji", "always: cite sources", "from now on, use metric units", "remember: I'm vegetarian".
+  - *Natural preference statements* become candidate rules: "I prefer metric units", "I hate it when you use bullet points". A candidate becomes a rule only when the user says the same thing again in a different message at least an hour later. Candidates are never injected, and they expire after 90 days without corroboration.
+  - Neither tier stores one-off tasks. A deadline, a named recipient, "now", or "this one" marks a task, not a preference ("always send the report to Dana by Friday" is a task).
+
+## Model-agnostic, with an honest caveat
+
+Imprint never calls a chat model. It works with anything that accepts a system prompt: a local model behind llama.cpp, Ollama or vLLM, or a hosted frontier model through its API. The default embedder (`all-MiniLM-L6-v2`) runs locally on CPU, so the user's messages aren't sent anywhere for learning.
+
+**The mechanism is model-agnostic. The effect is not.** How closely replies follow the calibration block depends on how well the host model follows instructions. A strong model will follow "Dry wit and occasional sarcasm are welcome" closely. A small model may follow it loosely, or not at all.
+
+## Integration contract
+
+Your host provides two things:
+
+1. **Each user message, with the time the user sent it.** Call `learn(text, timestamp=...)` before you build the prompt for that turn. Without a timestamp, Imprint still learns, but it records the time as unknown (never the processing time), skips confidence decay, and can't corroborate candidate rules. It logs a warning when this happens.
+2. **A place to inject text into the system prompt.** `directive()` returns the block, or `""` until `warmup` interactions (default 5) have passed. It stays identical byte for byte until something is actually learned, so it works with prompt caching.
+
+Everything beyond that is up to the host: memory, retrieval, tools, scheduling.
+
+## Install
+
+```bash
+pip install imprint-layer
+```
+
+The distribution is `imprint-layer`; the import is `imprint`. The default local embedder needs sentence-transformers: `pip install "imprint-layer[minilm]"`. Without it, pass your own embedder.
+
+A custom embedder is any object with a `name` and `embed(list_of_texts) -> array of shape (n, d)`. Pass it as `Imprint(..., embedder=MyEmbedder())`.
+
+## Examples
+
+- `examples/local_chat.py`: a chat loop against a local OpenAI-compatible server.
+- `examples/frontier_api.py`: the same injection, against a hosted API.
+
+Both are reference integrations to read and adapt. They aren't products.
+
+## Dashboard
+
+```bash
+imprint-dashboard my.profile.json -o dashboard.html
+```
+
+This renders a read-only static page: each dial's value and band, the standing rules, candidate rules and observation counts. Try it on `examples/sample.profile.json`.
+
+## Privacy
+
+A profile is personal data. It records how one person talks and what they've asked for. Keep profiles on the user's machine or in your own storage, and **never commit a real profile**. The included `.gitignore` excludes `*.profile.json`. Observations store short excerpts of the messages that moved a dial, and candidate rules store the user's own sentence.
+
+## What Imprint is not
+
+- Not a memory system. It doesn't store facts about the user or conversation history.
+- Not a hosted service. There's no account or server, and no data leaves your machine except through the chat calls you make yourself.
+- Not fine-tuning. Nothing about the model changes; Imprint only adds prompt text.
+- Not a safety layer. The calibration block is a preference, and your model's own policies still apply.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest                                   # deterministic fake embedder, no downloads
+IMPRINT_TEST_MINILM=1 pytest             # also run the real-embedder checks
+```
+
+## License
+
+MIT

imprint_layer-0.3.0/examples/frontier_api.py

@@ -0,0 +1,50 @@
+"""Reference integration: a hosted frontier model via an OpenAI-compatible API.
+
+Imprint itself runs locally (the default embedder never sends text anywhere).
+Only the chat request goes to the provider, with the calibration block in the
+system message, same as any other system prompt text.
+
+    pip install "imprint-layer[minilm]"
+    export API_BASE_URL=https://api.example.com/v1  API_KEY=...  API_MODEL=...
+    python examples/frontier_api.py "be a bit wittier. what's a good name for a cat?"
+
+Any provider that accepts a system prompt works the same way; adapt the
+request shape for providers with their own SDK.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+from datetime import datetime, timezone
+
+from imprint import Imprint
+
+
+def main() -> None:
+    text = " ".join(sys.argv[1:]) or "hello"
+    imp = Imprint("me.profile.json", axes_cache=".imprint/axes.npz")
+    imp.learn(text, timestamp=datetime.now(timezone.utc))
+    block = imp.directive()
+
+    system = "You are a helpful assistant."
+    if block:
+        system += f"\n\n## Behavior calibration\n{block}"
+    body = {
+        "model": os.environ["API_MODEL"],
+        "messages": [{"role": "system", "content": system},
+                     {"role": "user", "content": text}],
+    }
+    req = urllib.request.Request(
+        f"{os.environ['API_BASE_URL'].rstrip('/')}/chat/completions",
+        data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json",
+                 "Authorization": f"Bearer {os.environ['API_KEY']}"},
+    )
+    with urllib.request.urlopen(req, timeout=120) as r:
+        print(json.load(r)["choices"][0]["message"]["content"])
+
+
+if __name__ == "__main__":
+    main()

imprint_layer-0.3.0/examples/local_chat.py

@@ -0,0 +1,62 @@
+"""Reference integration: a local model behind an OpenAI-compatible server.
+
+Works with llama.cpp's llama-server, Ollama, LM Studio, vLLM, and similar.
+Per message: learn first (so a command like "be wittier" applies to this very
+reply), then rebuild the system prompt with the Imprint block.
+
+    pip install "imprint-layer[minilm]"
+    python examples/local_chat.py --base-url http://127.0.0.1:8080/v1 --model local
+
+This is a reference, not a product: no streaming, no history trimming.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import urllib.request
+from datetime import datetime, timezone
+
+from imprint import Imprint
+
+BASE_PROMPT = "You are a helpful assistant."
+
+
+def chat(base_url: str, model: str, messages: list[dict]) -> str:
+    req = urllib.request.Request(
+        f"{base_url.rstrip('/')}/chat/completions",
+        data=json.dumps({"model": model, "messages": messages}).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(req, timeout=300) as r:
+        return json.load(r)["choices"][0]["message"]["content"]
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--base-url", default="http://127.0.0.1:8080/v1")
+    ap.add_argument("--model", default="local")
+    ap.add_argument("--profile", default="me.profile.json")
+    a = ap.parse_args()
+
+    imp = Imprint(a.profile, axes_cache=".imprint/axes.npz")
+    history: list[dict] = []
+    while True:
+        try:
+            text = input("you> ").strip()
+        except EOFError:
+            break
+        if not text:
+            continue
+        # 1. Learn from the message, stamped with when the user sent it.
+        imp.learn(text, timestamp=datetime.now(timezone.utc))
+        # 2. Inject the calibration block into the system prompt.
+        block = imp.directive()
+        system = BASE_PROMPT + (f"\n\n## Behavior calibration\n{block}" if block else "")
+        history.append({"role": "user", "content": text})
+        reply = chat(a.base_url, a.model, [{"role": "system", "content": system}] + history)
+        history.append({"role": "assistant", "content": reply})
+        print(f"bot> {reply}\n")
+
+
+if __name__ == "__main__":
+    main()

imprint_layer-0.3.0/examples/sample.profile.json

@@ -0,0 +1,102 @@
+{
+  "schema": "imprint.profile/1",
+  "created": "2026-10-10T18:21:28.469+00:00",
+  "lastUpdated": "2026-10-10T18:21:28.469+00:00",
+  "interactions": 27,
+  "traits": {
+    "verbosity": {
+      "value": 0.39,
+      "confidence": 0.232,
+      "description": "concise and direct ↔ detailed explanations"
+    },
+    "autonomy": {
+      "value": 0.5,
+      "confidence": 0.2,
+      "description": "always ask first ↔ act on own judgment"
+    },
+    "formality": {
+      "value": 0.39,
+      "confidence": 0.232,
+      "description": "casual and conversational ↔ formal and precise"
+    },
+    "proactivity": {
+      "value": 0.5,
+      "confidence": 0.2,
+      "description": "wait for instructions ↔ suggest next steps unprompted"
+    },
+    "riskTolerance": {
+      "value": 0.61,
+      "confidence": 0.23979225590616793,
+      "description": "cautious claims ↔ confident, committed takes"
+    },
+    "humor": {
+      "value": 0.56,
+      "confidence": 0.232,
+      "description": "straight and earnest ↔ dry, sarcastic wit"
+    },
+    "warmth": {
+      "value": 0.5,
+      "confidence": 0.2,
+      "description": "matter-of-fact ↔ emotionally present"
+    },
+    "flirt": {
+      "value": 0.2,
+      "confidence": 0.2,
+      "description": "platonic ↔ playful romantic charge"
+    }
+  },
+  "rules": [
+    "Never use emoji",
+    "Always cite sources when you state a statistic"
+  ],
+  "candidateRules": [
+    {
+      "text": "I prefer metric units",
+      "polarity": 1,
+      "key": [
+        "metric",
+        "unit"
+      ],
+      "evidence": [
+        "2026-10-09T12:15:00.000+00:00"
+      ]
+    }
+  ],
+  "observations": [
+    {
+      "timestamp": "2026-10-09T08:15:00.000+00:00",
+      "trait": "verbosity",
+      "direction": -1.0,
+      "source": "steer",
+      "detail": "'be more concise' 0.500→0.390"
+    },
+    {
+      "timestamp": "2026-10-09T09:15:00.000+00:00",
+      "trait": "humor",
+      "direction": 1.0,
+      "source": "steer",
+      "detail": "'be wittier' 0.450→0.560"
+    },
+    {
+      "timestamp": "2026-10-09T12:15:00.000+00:00",
+      "trait": "riskTolerance",
+      "direction": -1.0,
+      "source": "vibe",
+      "detail": "score=-0.241"
+    },
+    {
+      "timestamp": "2026-10-09T13:15:00.000+00:00",
+      "trait": "formality",
+      "direction": -1.0,
+      "source": "steer",
+      "detail": "\"you're too formal\" 0.500→0.390"
+    },
+    {
+      "timestamp": "2026-10-09T14:15:00.000+00:00",
+      "trait": "riskTolerance",
+      "direction": 1.0,
+      "source": "steer",
+      "detail": "'be bolder' 0.488→0.610"
+    }
+  ]
+}

imprint_layer-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "imprint-layer"
+version = "0.3.0"
+description = "A personality calibration layer for any chat model: learns how one user wants an assistant to talk, from their own messages."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24"]
+keywords = ["llm", "personalization", "system-prompt", "assistant", "embeddings"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+]
+
+[project.optional-dependencies]
+minilm = ["sentence-transformers>=2.2"]
+test = ["pytest>=7"]
+
+[project.scripts]
+imprint-dashboard = "imprint.dashboard:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

imprint_layer-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

imprint_layer-0.3.0/src/imprint/__init__.py

@@ -0,0 +1,14 @@
+"""Imprint: a personality calibration layer for any chat model.
+
+Learns how one user wants an assistant to talk (8 trait dials plus standing
+rules) from their own messages, and renders a short plain-text block for the
+host to inject into the system prompt.
+"""
+from .core import Imprint, LearnResult, new_profile
+from .embedders import Embedder, MiniLMEmbedder
+from .steering import Steer, detect_steering
+from .traits import TRAIT_NAMES, band_step, describe
+
+__all__ = ["Imprint", "LearnResult", "new_profile", "Embedder", "MiniLMEmbedder",
+           "Steer", "detect_steering", "TRAIT_NAMES", "band_step", "describe"]
+__version__ = "0.3.0"