jsonfirst-openai

Stop sending raw user input to GPT.

JSONFIRST converts natural language into structured JSON intent before it reaches your OpenAI agent.

Intent → JSON → OpenAI → Execution.

JSONFIRST helps build reliable AI agents by converting natural language into structured JSON intent.

User input
    ↓
JSONFIRST (structured JDON)
    ↓
OpenAI (with governed context)
    ↓
Agent execution

Quick Example

const { parseIntent } = require('jsonfirst-openai');
const OpenAI = require('openai');

const jdon = await parseIntent("send a weekly report to the team", process.env.JSONFIRST_API_KEY);
// jdon.action.normalized → "send"
// jdon.object.type → "report"

const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: `Execute this intent: ${JSON.stringify(jdon)}` },
    { role: 'user', content: "send a weekly report to the team" }
  ]
});

Why

Without JSONFIRST:

User: "send a weekly report" → GPT decides what to do → unpredictable

With JSONFIRST:

User: "send a weekly report" → JDON: { action: "send", object: "report" } → GPT executes deterministically

Installation

npm install jsonfirst-openai

Get your API key at jsonfirst.com → Dashboard → API Console.

API

const { parseIntent } = require('jsonfirst-openai');

const jdon = await parseIntent(text, apiKey, { mode: 'ANTI_CREDIT_WASTE_V2' });

| Parameter | Type | Description | |---|---|---| | text | string | Raw natural language input | | apiKey | string | JSONFIRST API key | | options.mode | string | Governance mode (default: ANTI_CREDIT_WASTE_V2) |

Links

• JSONFIRST
• Documentation
• npm

License

MIT © JSONFIRST