psst-toolkit 1.2.0

Prompt Symbol Standard Technology - Token-efficient AI prompting with conversation sessions

A Specification for Token‑Efficient, Centrally‑Controllable AI Prompting

PSS: Prompt Symbol Standard

Overview

The Prompt Symbol Standard (PSS) is an open proposal for improving the cost-efficiency, consistency, and observability of LLM-driven applications. It introduces a developer-friendly symbolic compression framework that allows natural language prompts to be abstracted into concise, standardized symbols at runtime.

PSS is not about replacing human-readable prompt writing — it's about optimizing operations without disrupting developer workflows.

---

🔧 Workflow

The PSS workflow is intentionally ergonomic:

1. Author Naturally: Developers write prompts in natural language as usual.
2. Compress at Runtime: A tool like pss-compress automatically replaces long, standardized phrases with short symbolic tokens (e.g., ⊕summarize, ℧tone_friendly) before the prompt is sent to the LLM.
3. Restore for Debugging: Logs and outputs can be re-expanded into full-text form using pss-expand — like a linter or transpiler.

⚠️ Developers never need to memorize the symbol set. They only interact with it if looking at optimized diffs, logs, or internals.

This achieves human-readability at authoring time and machine-efficiency at execution time.

---

💡 Key Concepts

• Persistent Glossary Context: Instead of resending full prompt phrases repeatedly, PSS assumes the glossary lives in the system prompt or context window, allowing symbols to act like macros.
• Compression: Fewer tokens = lower cost. This is especially impactful at scale.
• Versionable Prompts: Symbols make diffs smaller and more meaningful (e.g., ⊕tone_friendly → ⊕tone_serious).
• Cross-Model Compatibility: PSS enables a shared symbolic interface across different LLMs with varying prompt quirks.

---

✅ Use Cases (Today)

You can use PSS principles in production now by:

• Defining an internal glossary (glossary.json) of your frequently used prompt fragments.
• Writing a preprocessor (pss-compress) that replaces known phrases with short symbols.
• Expanding logs later with pss-expand to aid debugging or observability.
• Storing the glossary and prompt files in Git for review/version control.

---

🧠 Why This Matters

Cost Savings

Compressing repeated prompt patterns into symbols can reduce token usage by hundreds or thousands per day, depending on traffic volume. If context is shared (via system prompt or API), the glossary cost becomes amortized, and individual prompts become drastically cheaper.

Developer Experience

With PSS, prompt authors continue writing in natural language. The system optimizes underneath them. No new syntax or cognitive load required.

Governance and Reliability

Prompts become diffable, auditable, and shareable using glossary.json — enabling reproducibility and easier debugging.

---

📦 Example

// glossary.json
{
  "⊕summarize": "Summarize the following text in 3 bullet points.",
  "℧tone_friendly": "Respond in a warm, casual tone.",
  "⊗legal_brief": "You are a legal assistant. Highlight key rulings and arguments."
}

// prompt.txt (before compression)
Please ⊗legal_brief on the case below. ⊕summarize. ℧tone_friendly

---

Definitive Industry‑Neutral Glossary (Core)

This glossary is intended to work across most AI workflows. Domain‑specific sets extend it but must not collide with core symbols.

Communication & Language

🗣 respond · 💬 dialog · 🅣 tone · 🧑‍🤝‍🧑 audience · 🕵️ persona

Retrieval & Input

🔍 search · 📥 parameters · 📤 specification · 🎯 intent

Structure & Formatting

📄 summary · 📊 structured‑output · 🧾 template · 🧩 insert · 🗃️ format‑type

Tool Use & Agents

⚙️ tool‑call · 🤖 agent‑plan · 📌 constraint · 🧠 LLM · 📦 memory

Planning & Reasoning

🧮 calculate · 🧭 plan · 🕹️ simulate

Instructional & Educational

🧑‍🏫 explain · ❓ quiz · ✔️ answer

Flow & Logic

⏱ deadline · 🔀 branch · 🕳 placeholder

Alignment, Ethics & Safety

🔐 restricted · 🛑 forbidden · 🚷 suppress · ⚖️ fairness · 🎭 adversarial · 📛 harm‑flag

Debugging & Evaluation

🧰 diagnostics · 📝 feedback · 🔍‍📝 audit

Control & Mutation

🄿 primary‑task · ✎ rewrite · 🔄 retry · 🚩 review

Data / Source Context

📚 multi‑doc · 🧬 dataset · 🛰️ external‑API · 🪄 synthetic‑flag

---

📚 Roadmap

• Developer-friendly glossary format (JSON)
• CLI: pss-compress, pss-expand
• VS Code extension (planned)
• Cross-domain glossary extensions (legal, coding, logistics, etc.)
• Open Glossary Repository
• Gradient-Encoded Visual Tokens (Appendix F)

---

📘 Appendices

Appendix A · Domain‑Specific Extensions

Domain glossaries extend the core set with industry-specific functions. Symbols must not collide with core glossary.

A.1 · Legal (@Legal)

⚖️📘 statute · 📜📝 legal argument · 🧾🔍 contract analysis · ⚖️🕵️ case lookup

A.2 · Healthcare (@Med)

💊📋 prescription summary · 🧬📝 genetic result interpretation · 🩺⚠️ risk factor warning · 🧠🔬 clinical trial summarization

A.3 · Software / Coding (@Dev)

🧪📄 test plan · 🧰⚙️ debug script · 📂📦 package structure · 🛠🧠 codegen plan

A.4 · Scientific Research (@Sci)

🔬📄 study summary · 📈📊 data visualization · 🧪📋 experiment design · 🧠🧪 hypothesis test

A.5 · Finance (@Fin)

📉📄 earnings summary · 🧾📈 balance sheet graph · 💰🔍 fraud risk audit · 📊💬 investor messaging

A.6 · Education (@Edu)

🧑‍🏫📄 lesson plan · 🧠❓ knowledge check · 📚🔄 curriculum alignment · 👩‍🎓📝 student feedback

A.7 · Marketing & Sales (@Mktg)

📢💬 ad copy · 📈🎯 campaign analysis · 🤝📄 sales script · 🛍️🧠 buyer persona summary

A.8 · Logistics & Supply Chain (@Logi)

📦🗺️ shipment route plan · 🚚🕒 delivery delay analysis · 🏭🔄 supply restock plan · 📊📦 warehouse load chart

---

Appendix B · Contribution Protocols & Versioning

• Use semantic versioning for all glossary files.
• Contributors must submit pull requests with changelogs.
• Conflicts must be resolved using namespace segmentation or symbol reassignment.
• Symbol additions must be justified with use case references.

---

Appendix C · JSON Schema for PSS Glossary

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["version", "glossary"],
  "properties": {
    "version": { "type": "string" },
    "glossary": {
      "type": "object",
      "patternProperties": {
        "^.{1,2}$": { "type": "string" }
      }
    }
  },
  "additionalProperties": false
}

---

Appendix D · CLI Tool Reference

• psst-compress input.txt → replaces phrases with symbols
• psst-expand input.pss → restores symbols to phrases
• psst-annotate file.pss → shows hoverable tooltips
• psst-compare old.json new.json → diffs two glossary versions
• psst-openai "prompt" --session name → send compressed prompts to OpenAI with conversation sessions

Session Management

The psst-openai tool supports conversation sessions that pay for glossary tokens only once per conversation:

# Start new conversation (pays for glossary once)
psst-openai "⊕summarize AI concepts" --session research

# Continue conversation (FREE glossary!)
psst-openai "📄provide_examples" --session research

# Manage sessions
psst-openai --list-sessions
psst-openai --delete-session research
psst-openai --session-info --session research

This dramatically reduces token costs for multi-turn conversations by sending symbol definitions only once per session.

---

Appendix E · Cross-Domain Conflict Resolution

• Each domain (legal, healthcare, etc.) uses a prefix namespace: @Legal, @Med, @Dev
• Collisions must be resolved by aliasing or sub‑scoping (e.g., @Legal.⚖️ vs @Med.⚖️)
• Core glossary is reserved and cannot be overridden
• Shared terms must be submitted for review under a new @Common namespace

---

Appendix F · Gradient-Encoded Visual Tokens (Future)

As the expressive capacity of Unicode symbols becomes saturated, future-proofing PSS will involve visual token encoding.

F.1 Overview

• Visually encoded 16×16 tokens rendered as SVG or bitmap
• Each token maps to a glossary symbol or prompt clause
• Enables multimodal inline recognition in advanced LLMs

F.2 Examples

• Colored dot matrix grid representing 🧾📈
• QR-style pattern encoding the intent: "summarize and graph financial results"
• Visual hash for multi-symbol phrase chains like 🔍📄🧾

These tokens can be embedded into agent dashboards, LLM UIs, or printed for cross-device coordination.

More advanced encodings will emerge as LLMs evolve toward full multimodal symbol comprehension.---

🧪 Is This Ready for Production?

Not yet — but the principles can be applied today.

PSS is not a mature ecosystem yet. Tooling, IDE plugins, and adoption are in early development. However, internal use of a glossary + preprocessor can give you 80% of the benefits immediately.

This project is in active development. Contributions welcome.

---

🤝 Attribution

Proposal and specification led by [Your Name or Org]. Contributions, discussions, and forks are welcome. See CONTRIBUTING.md for guidelines.