Metadata-Version: 2.4
Name: psst-toolkit
Version: 1.0.0
Summary: Prompt Symbol Standard Technology - Token-efficient AI prompting
Home-page: https://github.com/goldsteinmarcmd/pss
Author: Marc Goldstein
Author-email: marcgoldstein@example.edu
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Intended Audience :: Developers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

*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

```json
// 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."
}
```

```txt
// 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

* [x] Developer-friendly glossary format (JSON)
* [x] CLI: `pss-compress`, `pss-expand`
* [x] VS Code extension (planned)
* [x] 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

```json
{
  "$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

- `pss-compress input.txt` → replaces phrases with symbols
- `pss-expand input.pss` → restores symbols to phrases
- `pss-annotate file.pss` → shows hoverable tooltips
- `pss-compare old.json new.json` → diffs two glossary versions

---

## 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.
