Skip to content

Commit b4420af

Browse files
PredictabilityAtScalePredictabilityAtScale
committed
WEBSITE: Updated copy to target developers
1 parent 5291ba8 commit b4420af

2 files changed

Lines changed: 202 additions & 61 deletions

File tree

‎website/index.html‎

Lines changed: 179 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -59,141 +59,259 @@
5959
<a class="brand" href="#top" aria-label="PromptOpsKit home">PromptOpsKit</a>
6060
<nav aria-label="Primary">
6161
<a href="#why">Why</a>
62+
<a href="#what">What</a>
63+
<a href="#quickstart">How</a>
6264
<a href="#features">Features</a>
63-
<a href="#quickstart">Quick start</a>
6465
<a href="#faq">FAQ</a>
65-
<a href="#oss">Open source</a>
6666
</nav>
6767
<a class="button button-primary" href="https://github.com/PredictabilityAtScale/promptopskit">GitHub</a>
6868
</div>
6969
</header>
7070

7171
<main id="top">
72+
<!-- ─── HERO ─── -->
7273
<section class="hero container">
7374
<p class="eyebrow">Open-source prompt infrastructure</p>
74-
<h1>Ship AI prompts with the same rigor as application code.</h1>
75+
<h1>Version-control your AI prompts like application code.</h1>
7576
<p class="lead">
76-
PromptOpsKit is a developer-first toolkit and CLI for authoring prompts in Markdown,
77-
validating schema and variables before runtime, and rendering provider-specific request bodies
78-
without locking you into a transport stack.
77+
PromptOpsKit turns prompts into plain Markdown files that live in your repo.
78+
Model settings, sampling parameters, environment overrides, variable placeholders,
79+
and shared instructions are all defined in one file — then rendered into ready-to-send
80+
request bodies for OpenAI, Anthropic, Gemini, or OpenRouter.
7981
</p>
8082
<div class="hero-actions">
8183
<a class="button button-primary" href="https://www.npmjs.com/package/promptopskit">Install from npm</a>
82-
<a class="button" href="https://github.com/PredictabilityAtScale/promptopskit#quick-start">Read the quick start</a>
84+
<a class="button" href="#quickstart">Quick start</a>
8385
</div>
84-
<pre><code>npm install promptopskit
85-
npx promptopskit init ./prompts
86-
promptopskit validate ./prompts --strict</code></pre>
86+
<pre><code>npm install promptopskit</code></pre>
8787
</section>
8888

89+
<!-- ─── THE PROBLEM ─── -->
8990
<section id="why" class="container section">
90-
<h2>Why teams adopt PromptOpsKit</h2>
91+
<h2>The problem: prompts are invisible infrastructure</h2>
92+
<p class="section-intro">
93+
Most teams embed prompts as string literals scattered across application code.
94+
Model parameters live in config files. Environment differences are handled with
95+
if/else branches. When a prompt changes, there is no diff to review, no schema to
96+
validate, and no way to share instructions across features without copy-pasting.
97+
</p>
9198
<div class="grid three">
9299
<article class="card">
93-
<h3>Predictable prompt changes</h3>
94-
<p>Store prompts in markdown with front matter so every change is diffable, reviewable, and auditable.</p>
100+
<h3>Prompts buried in code</h3>
101+
<p>String constants and template literals are hard to diff, review, or audit. Prompt changes hide inside application commits with no clear ownership.</p>
95102
</article>
96103
<article class="card">
97-
<h3>Portable provider output</h3>
98-
<p>Generate request bodies for OpenAI, Anthropic, Gemini, and OpenRouter while keeping network logic in your app.</p>
104+
<h3>Settings scattered everywhere</h3>
105+
<p>Model names, temperature, reasoning effort, and max tokens live in separate config objects — disconnected from the prompt they belong to.</p>
99106
</article>
100107
<article class="card">
101-
<h3>Safer releases</h3>
102-
<p>Catch invalid schema, unresolved variables, and malformed composition before your production calls fail.</p>
108+
<h3>Duplication across environments</h3>
109+
<p>Dev uses a cheaper model. Prod uses a different one. Free-tier caps output tokens. Each variation means another copy of the same prompt.</p>
103110
</article>
104111
</div>
105112
</section>
106113

107-
<section id="features" class="container section">
108-
<h2>Prompt management features for engineering teams</h2>
114+
<!-- ─── THE SOLUTION (WHAT) ─── -->
115+
<section id="what" class="container section">
116+
<h2>The solution: prompts as versioned, composable Markdown files</h2>
117+
<p class="section-intro">
118+
PromptOpsKit gives every prompt a single Markdown file that captures everything —
119+
model settings, sampling parameters, environment overrides, variable declarations,
120+
and composable includes — so prompts are diffable, reviewable, and portable.
121+
</p>
109122
<div class="grid two">
110123
<article class="card">
111-
<h3>Authoring format engineers already trust</h3>
112-
<ul>
113-
<li>Markdown files with YAML front matter</li>
114-
<li>H1 sections for system instructions and prompt template</li>
115-
<li><code>{{ variable }}</code> interpolation and strict checks</li>
116-
</ul>
124+
<h3>Version-controlled prompts</h3>
125+
<p>Each prompt is a <code>.md</code> file with YAML front matter. It diffs in pull requests, merges through your normal workflow, and has a clear history in git.</p>
117126
</article>
118127
<article class="card">
119-
<h3>Composition and overrides without duplication</h3>
120-
<ul>
121-
<li><code>includes</code> for shared policy, tone, and safety blocks</li>
122-
<li>Environment and tier-specific overrides</li>
123-
<li>Deterministic precedence: base → env → tier → runtime</li>
124-
</ul>
128+
<h3>Model &amp; parameter settings in one place</h3>
129+
<p>Model name, temperature, top_p, reasoning effort, max output tokens, and response format are declared in front matter — right next to the prompt text they govern.</p>
125130
</article>
126131
<article class="card">
127-
<h3>CLI for local and CI pipelines</h3>
128-
<ul>
129-
<li><code>init</code>, <code>validate</code>, <code>render</code>, <code>inspect</code>, <code>compile</code>, and <code>skill</code></li>
130-
<li>Pre-compile prompts to JSON/ESM artifacts</li>
131-
<li>Use in pre-merge checks and release workflows</li>
132-
</ul>
132+
<h3>Environment &amp; tier overrides</h3>
133+
<p>Define <code>environments</code> and <code>tiers</code> in front matter to swap models and parameters for dev/prod or free/pro without duplicating the prompt file.</p>
133134
</article>
134135
<article class="card">
135-
<h3>No transport lock-in</h3>
136-
<ul>
137-
<li>Adapters return request body only</li>
138-
<li>You keep control of auth, retries, headers, and observability</li>
139-
<li>Integrates with existing HTTP and infra standards</li>
140-
</ul>
136+
<h3>Data insertion with variables</h3>
137+
<p><code>{{ variable }}</code> placeholders inject runtime data into prompts. Declared inputs are validated before rendering — missing or extra variables are caught early.</p>
138+
</article>
139+
<article class="card">
140+
<h3>Composable shared instructions</h3>
141+
<p><code>includes</code> lets you define tone, policy, or safety instructions once and prepend them to any prompt. No copy-paste, no drift, with circular dependency detection.</p>
142+
</article>
143+
<article class="card">
144+
<h3>Provider-portable output</h3>
145+
<p>Render the same prompt for OpenAI, Anthropic, Gemini, or OpenRouter. Each adapter produces the correct request body shape — you own the HTTP call.</p>
141146
</article>
142147
</div>
143148
</section>
144149

150+
<!-- ─── HOW IT WORKS (QUICK START) ─── -->
145151
<section id="quickstart" class="container section">
146-
<h2>PromptOpsKit quick start</h2>
147-
<div class="grid two">
152+
<h2>How it works</h2>
153+
154+
<div class="quickstart-steps">
148155
<article class="card">
149-
<h3>1) Install and scaffold</h3>
156+
<h3>1. Install and scaffold</h3>
150157
<pre><code>npm install promptopskit
151158
npx promptopskit init ./prompts</code></pre>
159+
<p>Creates a <code>prompts/</code> directory with starter files and a shared instructions folder.</p>
160+
</article>
161+
162+
<article class="card">
163+
<h3>2. Write a prompt file</h3>
164+
<p>One Markdown file defines everything: model, parameters, overrides, variables, includes, and prompt text.</p>
165+
<pre><code>---
166+
id: support.reply
167+
schema_version: 1
168+
provider: openai
169+
model: gpt-5.4
170+
reasoning:
171+
effort: medium
172+
sampling:
173+
temperature: 0.7
174+
context:
175+
inputs:
176+
- user_message
177+
- app_context
178+
includes:
179+
- ./shared/tone.md
180+
environments:
181+
dev:
182+
model: gpt-5.4-mini
183+
sampling:
184+
temperature: 0.2
185+
prod:
186+
model: gpt-5.4
187+
tiers:
188+
free:
189+
model: gpt-5.4-mini
190+
pro:
191+
model: gpt-5.4
192+
---
193+
194+
# System instructions
195+
196+
You are a helpful support assistant working in {{ app_context }}.
197+
198+
# Prompt template
199+
200+
{{ user_message }}</code></pre>
152201
</article>
202+
153203
<article class="card">
154-
<h3>2) Render for your target provider</h3>
204+
<h3>3. Render for any provider</h3>
205+
<p>Load the prompt, supply variables, and get a ready-to-send request body.</p>
155206
<pre><code>import { createPromptOpsKit } from 'promptopskit';
156207

157208
const kit = createPromptOpsKit({ sourceDir: './prompts' });
158-
const result = await kit.renderPrompt({
209+
210+
const { request } = await kit.renderPrompt({
159211
path: 'support/reply',
160212
provider: 'openai',
161-
variables: { user_message: 'How do I reset my password?' }
213+
environment: 'prod',
214+
tier: 'pro',
215+
variables: {
216+
user_message: 'How do I reset my password?',
217+
app_context: 'Account settings page',
218+
},
219+
});
220+
221+
// request.body is shaped for OpenAI — send it with your own HTTP client
222+
const res = await fetch('https://api.openai.com/v1/chat/completions', {
223+
method: 'POST',
224+
headers: {
225+
'Content-Type': 'application/json',
226+
Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
227+
},
228+
body: JSON.stringify(request.body),
162229
});</code></pre>
163230
</article>
164231
</div>
165232
</section>
166233

234+
<!-- ─── FEATURES ─── -->
235+
<section id="features" class="container section">
236+
<h2>Features for engineering teams</h2>
237+
<div class="grid two">
238+
<article class="card">
239+
<h3>Validation &amp; schema checks</h3>
240+
<ul>
241+
<li>Zod schema validation for front matter</li>
242+
<li>Levenshtein-based "did you mean?" for field typos</li>
243+
<li>Variable usage checks — missing and unused inputs</li>
244+
<li>Strict mode fails on any unresolved placeholder</li>
245+
</ul>
246+
</article>
247+
<article class="card">
248+
<h3>CLI for local dev and CI</h3>
249+
<ul>
250+
<li><code>init</code> — scaffold starter prompts</li>
251+
<li><code>validate</code> — check all prompts before merge</li>
252+
<li><code>compile</code> — pre-compile <code>.md</code> → JSON or ESM</li>
253+
<li><code>render</code> — preview output with test variables</li>
254+
<li><code>inspect</code> — print normalized prompt as JSON</li>
255+
<li><code>skill</code> — deploy AI agent instructions</li>
256+
</ul>
257+
</article>
258+
<article class="card">
259+
<h3>Compiled artifacts for production</h3>
260+
<ul>
261+
<li>Pre-compile prompts to JSON or ESM — skip parsing at runtime</li>
262+
<li>Auto mode loads compiled when available, falls back to source</li>
263+
<li>LRU cache with mtime-based invalidation during development</li>
264+
</ul>
265+
</article>
266+
<article class="card">
267+
<h3>No transport lock-in</h3>
268+
<ul>
269+
<li>Adapters return request body only — no HTTP client bundled</li>
270+
<li>You control auth, retries, headers, and observability</li>
271+
<li>Works with any fetch wrapper, SDK, or infrastructure</li>
272+
</ul>
273+
</article>
274+
</div>
275+
</section>
276+
277+
<!-- ─── FAQ ─── -->
167278
<section id="faq" class="container section">
168279
<h2>Frequently asked questions</h2>
169280
<div class="grid two">
170281
<article class="card">
171282
<h3>Is PromptOpsKit only for one model provider?</h3>
172-
<p>No. It supports OpenAI, Anthropic, Gemini, and OpenRouter adapters out of the box.</p>
283+
<p>No. It ships with adapters for OpenAI, Anthropic, Gemini, and OpenRouter. Each produces the correct request body shape for that API.</p>
284+
</article>
285+
<article class="card">
286+
<h3>Does it make HTTP requests for me?</h3>
287+
<p>No. PromptOpsKit returns request-body payloads. Your application owns transport, auth, retries, and headers.</p>
173288
</article>
174289
<article class="card">
175-
<h3>Does PromptOpsKit make HTTP requests?</h3>
176-
<p>No. It returns request-body payloads so your app controls auth, transport, retries, and headers.</p>
290+
<h3>Can I validate prompts in CI?</h3>
291+
<p>Yes. Run <code>promptopskit validate ./prompts --strict</code> in your pipeline to catch schema errors, missing variables, and broken includes before deploy.</p>
177292
</article>
178293
<article class="card">
179-
<h3>Can we validate prompts in CI before deploy?</h3>
180-
<p>Yes. Use the CLI validate and compile commands in your CI pipeline to catch issues before release.</p>
294+
<h3>How do overrides work?</h3>
295+
<p>Define <code>environments</code> and <code>tiers</code> in front matter. At render time, pass <code>environment</code> and <code>tier</code> to apply the right model and parameter set. Precedence: base → env → tier → runtime.</p>
296+
</article>
297+
<article class="card">
298+
<h3>What does composability look like?</h3>
299+
<p>Add an <code>includes</code> array in front matter pointing to other <code>.md</code> files. Their system instructions are prepended to the current prompt. Circular includes are detected automatically.</p>
181300
</article>
182301
<article class="card">
183302
<h3>Is PromptOpsKit open source?</h3>
184-
<p>Yes. The project is MIT-licensed and maintained in a public GitHub repository.</p>
303+
<p>Yes. MIT-licensed, maintained on GitHub, and designed so you never depend on a hosted service.</p>
185304
</article>
186305
</div>
187306
</section>
188307

308+
<!-- ─── OPEN SOURCE ─── -->
189309
<section id="oss" class="container section">
190-
<h2>Open source and production-ready defaults</h2>
191-
<p>
192-
PromptOpsKit is MIT-licensed and designed for teams that need testable prompt operations.
193-
Use source prompts in development and pre-compiled artifacts in production for speed and reliability.
194-
</p>
310+
<h2>Open source and production-ready</h2>
195311
<p>
196-
Explore docs, examples, and API details in the repository.
312+
PromptOpsKit is MIT-licensed and built for teams that treat prompt engineering as a
313+
first-class engineering discipline. Use source prompts in development, compiled
314+
artifacts in production, and the CLI in CI — all from one <code>npm install</code>.
197315
</p>
198316
<a class="button button-primary" href="https://github.com/PredictabilityAtScale/promptopskit">View repository</a>
199317
</section>

‎website/styles.css‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,29 @@ ul {
189189
color: inherit;
190190
}
191191

192+
.section-intro {
193+
max-width: 68ch;
194+
color: var(--muted);
195+
font-size: 1.05rem;
196+
margin-bottom: 1.5rem;
197+
}
198+
199+
.quickstart-steps {
200+
display: flex;
201+
flex-direction: column;
202+
gap: 1.25rem;
203+
margin-top: 1.25rem;
204+
}
205+
206+
.quickstart-steps .card h3 {
207+
margin-bottom: 0.5rem;
208+
}
209+
210+
.quickstart-steps .card p {
211+
color: var(--muted);
212+
font-size: 0.95rem;
213+
}
214+
192215
@media (max-width: 900px) {
193216
nav {
194217
display: none;

0 commit comments

Comments
 (0)