# Npcpy Prompting

> npcpy LLM prompting and JSON formatting patterns.

- Skill: `npc-worldwide/npcpy-prompting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add npc-worldwide/npcpy-prompting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/npc-worldwide/npcpy-prompting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: npc-worldwide (https://skillmd.com/u/npc-worldwide)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/npc-worldwide/npcpy-prompting

---


# npcpy-prompting

npcpy LLM prompting and JSON formatting patterns.

## Imports

Always import at module level:
- `from npcpy.llm_funcs import get_llm_response`
- `from npcpy.npc_compiler import NPC`
- `from npcpy.gen.response import get_litellm_response` (only for streaming)


## Basic-Call

`get_llm_response(prompt, model, provider, **kwargs)` — first arg is POSITIONAL.
Do NOT write `prompt=prompt`. Do NOT use `NPC.call()`. The function is module-level.


## Json-Mode

Pass `format="json"` for structured output.
npcpy parses internally. Access via `response["response"]`.
Never call `json.loads()` manually.


## Npc-Object

Create an `NPC` to hold model, provider, and primary_directive.
Pass it as `npc=npc_instance` so npcpy reads those values:
```python
npc = NPC(name="...", primary_directive="...", model="...", provider="...")
response = get_llm_response(prompt, npc=npc, format="json", temperature=0.7)
data = response["response"]
```


## Messages

Pass conversation history as `messages=[{"role": "system", "content": msg}]`.
This is a kwarg like any other. It does not persist between calls.


## Parameters

Sampling kwargs to `get_llm_response`:
- `temperature`, `top_p`, `top_k`, `max_tokens`
- `stream=True` returns a generator in `response["response"]`


## Streaming

For token-level streaming use `get_litellm_response` with `stream=True`.
For segment-level use `get_llm_response(..., stream=True)` and iterate `response["response"]`.


## Anti-Patterns

- Do NOT use `json.loads(response["response"])`.
- Do NOT call `response.get("response")` and then parse it again.
- Do NOT assume `response` is a string when `format="json"` is used.


## Prompt-Formatting

When constructing prompt strings in Python:
- Use `f"""..."""` for all multiline prompts. Do NOT use implicit string concatenation.
- Do NOT put multiline strings directly in a `return` statement. Assign to a variable first, then return it.
- The closing `"""` must be at the same indentation as the variable assignment.
- Do NOT escape braces as `{{` inside f-strings. If you need literal curly braces in the prompt output, use explicit string concatenation:
  ```python
  prompt = f"""Write a JSON response like this:""" + """\n{'key': 'value'}\n"""
  ```
- Never use `f"..." f"..."` on adjacent lines or in parentheses expecting the parser to concatenate them.