> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Xprompt

# Xprompt Package Cheatsheet

Root namespace: `Cognesy\Xprompt`

This file is a quick, code-aligned map of the package surface.
For narrative guidance and design rationale, see `packages/xprompt/concept.md`.

## 1. Prompt (base class)

```php theme={null}
abstract class Prompt implements \Stringable
```

### Properties

```php theme={null}
public string $model = '';
public bool $isBlock = false;
public string $templateFile = '';
public ?string $templateDir = null;
public array $blocks = [];                // block class names for template composition
```

### Static Constructors

```php theme={null}
Prompt::make(): static
Prompt::with(mixed ...$ctx): static       // bind context
```

### Rendering

```php theme={null}
render(mixed ...$ctx): string             // merge ctx, call body(), flatten
__toString(): string                      // delegates to render()
```

### Override Point

```php theme={null}
body(mixed ...$ctx): string|array|null    // return string, array of renderables, or null
```

### Metadata & Introspection

```php theme={null}
meta(): array                             // YAML front matter from templateFile
variables(): array                        // template variable names
validationErrors(mixed ...$ctx): array    // missing/extra variable checks
```

### Config

```php theme={null}
withConfig(TemplateEngineConfig $config): static  // clone with config
```

## 2. NodeSet (structured data prompt)

```php theme={null}
class NodeSet extends Prompt
```

### Properties

```php theme={null}
public string $dataFile = '';             // YAML file path
public string $sortKey = '';              // sort field
public array $items = [];                 // inline data alternative
```

### Methods

```php theme={null}
nodes(mixed ...$ctx): array              // load + sort items; override for dynamic data
renderNode(int $index, array $node, mixed ...$ctx): string  // format one item; override for custom
body(mixed ...$ctx): array               // maps nodes -> renderNode
```

### Default Node Format

```
1. **Label** -- content
   - child content
```

## 3. PromptRegistry

```php theme={null}
class PromptRegistry
```

### Constructor

```php theme={null}
new PromptRegistry(
    ?TemplateEngineConfig $config = null,
    array $overrides = [],                // ['name' => VariantClass::class]
)
```

### Registration & Retrieval

```php theme={null}
register(string $name, string $class): void       // same name = variant
registerClass(string $class): void                 // uses #[AsPrompt] or $promptName
get(string $name): Prompt                          // applies overrides
has(string $name): bool
```

### Introspection

```php theme={null}
names(bool $includeBlocks = false): array
all(bool $includeBlocks = false): iterable     // yields name => class
variants(string $name): array                  // variant classes for a name
```

## 4. AsPrompt Attribute

```php theme={null}
#[\Attribute(\Attribute::TARGET_CLASS)]
class AsPrompt
{
    public function __construct(public readonly string $name) {}
}
```

Usage:

```php theme={null}
#[AsPrompt("reviewer.analyze")]
class Analyze extends Prompt { ... }
```

## 5. PromptDiscovery

```php theme={null}
class PromptDiscovery
```

```php theme={null}
static register(PromptRegistry $registry, array $namespaces = []): void
```

Discovery priority: `#[AsPrompt]` > `$promptName` property > FQCN convention.

## 6. flatten()

```php theme={null}
function flatten(mixed $node, array $ctx = []): string
```

* `null` -> `''`
* `string` -> pass through
* `Prompt` -> `$node->render(...$ctx)`
* `array` -> recurse, join with `"\n\n"`, skip empties
* `Stringable` -> `(string) $node`

## Minimal Examples

### Inline prompt

```php theme={null}
class Persona extends Prompt
{
    public function body(mixed ...$ctx): string
    {
        return "You are a {$ctx['role']} expert.";
    }
}

echo Persona::with(role: 'security');
```

### Template-backed prompt

```php theme={null}
class Analyze extends Prompt
{
    public string $templateFile = 'analyze.md';
    public string $templateDir = __DIR__;
}

echo Analyze::with(content: $doc);
```

### Composition

```php theme={null}
class Review extends Prompt
{
    public function body(mixed ...$ctx): array
    {
        return [
            Persona::make(),
            ScoringRubric::with(format: 'detailed'),
            "## Document\n\n" . $ctx['content'],
            $ctx['strict'] ?? false ? Constraints::make() : null,
        ];
    }
}
```

### Integration with StructuredOutput / Agents

```php theme={null}
// StructuredOutput
StructuredOutput::with(
    system: Review::with(content: $doc, strict: true),
    responseModel: MyModel::class,
)->get();

// Agents (via AgentContext)
$context->withSystemPrompt(Review::with(content: $doc));
```

### Variant swap

```php theme={null}
$registry = new PromptRegistry(
    overrides: ['reviewer.analyze' => AnalyzeCoT::class],
);
$prompt = $registry->get('reviewer.analyze'); // returns AnalyzeCoT
```