### Persistent Store Operations (C)

Source: https://context7.com/drqedwards/the_boy/llms.txt

Demonstrates basic operations for the file-backed key-value store in C, including opening, putting, getting, checking existence, flushing, and closing.

```c
#include "pmll_core.h"

pmll_store_t *store = store_open(".pmll_store");

/* Write */
store_put(store, "run:cycle:1", "complete");
store_put(store, "run:cycle:2", "running");

/* Read */
const char *val = store_get(store, "run:cycle:1");
printf("cycle:1 = %s\n", val);   /* Expected: complete */

/* Check existence */
printf("exists: %d\n", store_exists(store, "run:cycle:99")); /* 0 */

/* Flush to disk and close */
store_flush(store);
store_close(store);
```

--------------------------------

### Python FFI Bindings for C Core

Source: https://context7.com/drqedwards/the_boy/llms.txt

Wraps the C shared library using ctypes for Python integration. Requires the C library to be built first. This example shows initialization, dispatching a signal, querying a node, and cleanup.

```python
# Requires the C library to be built first: make
from bindings.python.pmll import PmllCore

core = PmllCore(
    roster_path="data/rosters_mock.csv",
    store_path=".pmll_store",
)

core.init()

# Dispatch a signal through the C core
core.dispatch({
    "type":      "score_update",
    "entity_id": "player_1",
    "value":     8.0,
})

# Query a node
node = core.kg_get("player_1")
print("Node via C core:", node)
# Expected: {'id': 'player_1', 'name': '...', 'score': 8.0, ...}

core.flush()
core.free()
```

--------------------------------

### Core C API: Initialization, Dispatch, Query, and Cleanup

Source: https://context7.com/drqedwards/the_boy/llms.txt

Demonstrates the core C API for initializing the agent context, dispatching signals, querying the knowledge graph, and freeing resources. Error handling for initialization is included.

```c
#include "pmll_core.h"
#include <stdio.h>

int main(void) {
    /* Initialise agent context */
    pmll_ctx_t *ctx = pmll_init("data/rosters_mock.csv", ".pmll_store");
    if (!ctx) { fprintf(stderr, "Init failed\n"); return 1; }

    /* Dispatch a signal */
    pmll_signal_t sig = {
        .type      = "score_update",
        .entity_id = "player_1",
        .value     = 9.5,
    };
    int ret = pmll_dispatch(ctx, &sig);
    printf("Dispatch returned: %d\n", ret);   /* Expected: 0 (OK) */

    /* Query a node from the embedded KG */
    pmll_node_t *node = pmll_kg_get(ctx, "player_1");
    if (node) printf("Name: %s, Score: %.1f\n", node->name, node->score);

    /* Persist state and free */
    pmll_flush(ctx);
    pmll_free(ctx);
    return 0;
}
```

--------------------------------

### PmllAgent: Initialization, Cycle Run, and Signal Emission (Python)

Source: https://context7.com/drqedwards/the_boy/llms.txt

Shows how to initialize the PmllAgent, run a processing cycle, and emit custom signals. The agent orchestrates the store, knowledge graph, and signal processor.

```python
from pmll_agent.agent import PmllAgent

agent = PmllAgent(
    roster_path="data/rosters_mock.csv",
    store_path=".pmll_store",
)

# Initialise — loads rosters, builds KG, restores persisted state
agent.init()

# Run one processing cycle
result = agent.run_cycle()
print("Cycle result:", result)
# Expected: {'processed': N, 'signals_dispatched': M, 'errors': []}

# Emit a custom signal into the running agent
agent.emit({"type": "score_update", "entity_id": "player_1", "value": 8.5})

# Graceful shutdown — flushes store to disk
agent.shutdown()
```

--------------------------------

### Build and Run C Core (Makefile)

Source: https://context7.com/drqedwards/the_boy/llms.txt

Commands to build the C core implementation and run its bundled demo script. Assumes you are in the extracted pmll_signal_agent_c/ directory.

```bash
# From inside the extracted pmll_signal_agent_c/ directory
make            # builds libpmll.so + pmll_cli binary
make clean      # remove build artefacts

# Run the bundled demo script
bash scripts/demo.sh

# Expected:
# Building PMLL Signal Agent (C core)...
# Loading rosters from data/rosters_mock.csv
# Initialising persistent store...
# Running signal demo...
# Done. Processed N records.
```

--------------------------------

### Command-Line Interface Operations

Source: https://context7.com/drqedwards/the_boy/llms.txt

Demonstrates using the `pmll_cli` binary for various operations including loading data, dispatching signals, querying nodes, and flushing the store.

```bash
# Load rosters and build the KG
./pmll_cli load --roster data/rosters_mock.csv --store .pmll_store

# Dispatch a signal
./pmll_cli signal --type score_update --entity player_1 --value 9.5
# Expected: OK: signal dispatched

# Query a node
./pmll_cli get --entity player_1
# Expected: id=player_1 name=Alice score=9.50 active=true

# Flush persisted state
./pmll_cli flush --store .pmll_store
# Expected: Store flushed. N entries written.

# Show help
./pmll_cli --help
```

--------------------------------

### Roster Management: Load, Iterate, and Free (C)

Source: https://context7.com/drqedwards/the_boy/llms.txt

Shows how to load a roster table from a CSV file, iterate through its entries, and free the allocated memory. Basic error checking for loading is implied.

```c
#include "pmll_core.h"
#include "csv.h"

/* Standalone roster loading example */
roster_table_t *tbl = roster_load("data/rosters_mock.csv");
if (!tbl) { /* handle error */ }

printf("Total rosters: %zu\n", tbl->count);

for (size_t i = 0; i < tbl->count; i++) {
    roster_entry_t *e = &tbl->entries[i];
    printf("  [%zu] id=%s name=%s score=%.2f\n",
           i, e->id, e->name, e->score);
}

roster_table_free(tbl);
```

--------------------------------

### SignalProcessor: Register Handler and Dispatch Signal (Python)

Source: https://context7.com/drqedwards/the_boy/llms.txt

Demonstrates registering a handler for a specific signal type and dispatching a signal. The processor validates signals against the knowledge graph before dispatching.

```python
from pmll_agent.signals import SignalProcessor
from pmll_agent.kg import KnowledgeGraph

kg = KnowledgeGraph()
kg.add_node("player_1", attributes={"name": "Alice", "score": 9.7})

processor = SignalProcessor(graph=kg)

# Register a handler for a signal type
@processor.on("score_update")
def handle_score_update(signal):
    node = kg.get_node(signal["entity_id"])
    print(f"Updating score for {node['name']}: {signal['value']}")

# Dispatch a signal
processor.dispatch({
    "type": "score_update",
    "entity_id": "player_1",
    "value": 10.0,
})
# Expected: Updating score for Alice: 10.0

# Dispatch an unrecognised signal (should be handled gracefully)
processor.dispatch({"type": "unknown_event", "entity_id": "player_1"})
```

--------------------------------

### Initialize pmll_agent Package

Source: https://context7.com/drqedwards/the_boy/llms.txt

Import the public API of the pmll_agent package. This provides access to the agent class, knowledge graph helpers, signal utilities, roster loader, and parser functions.

```python
# Install / run from the extracted zip
# unzip pmll_signal_agent.zip && cd pmll_signal_agent

from pmll_agent import (
    PmllAgent,        # top-level orchestrator
    KnowledgeGraph,   # kg.py — graph construction & query
    SignalProcessor,  # signals.py — signal ingestion & dispatch
    RosterStore,      # store.py — persistent KV store
    load_rosters,     # rosters.py — CSV → roster objects
    parse_record,     # parsers.py — raw row → typed dict
)

print("pmll_agent package loaded successfully")
# Expected: pmll_agent package loaded successfully
```

--------------------------------

### Build and Query KnowledgeGraph

Source: https://context7.com/drqedwards/the_boy/llms.txt

Construct an in-memory knowledge graph from roster records using `KnowledgeGraph`. Supports adding nodes with attributes and creating edges to represent relationships, enabling agent reasoning.

```python
from pmll_agent.kg import KnowledgeGraph
from pmll_agent.rosters import load_rosters

kg = KnowledgeGraph()

# Ingest rosters into the graph
rosters = load_rosters("data/rosters_mock.csv")
for record in rosters:
    kg.add_node(record["id"], attributes=record)

# Add relationships
kg.add_edge("player_1", "team_A", relation="member_of")
kg.add_edge("player_2", "team_A", relation="member_of")
kg.add_edge("team_A",   "league_1", relation="plays_in")

# Query neighbours
neighbours = kg.neighbours("team_A")
print("team_A neighbours:", neighbours)
# Expected: ['player_1', 'player_2', 'league_1']  (order may vary)
```

--------------------------------

### Manage Persistent State with RosterStore

Source: https://context7.com/drqedwards/the_boy/llms.txt

Utilize `RosterStore` for a file-system-backed key-value store that persists data across process restarts. This is ideal for resumable agent runs and incremental state management.

```python
from pmll_agent.store import RosterStore

store = RosterStore(path=".pmll_store")

# Write entries
store.put("agent:run:1", {"status": "complete", "processed": 120})
store.put("agent:run:2", {"status": "running",  "processed": 45})

# Read back
entry = store.get("agent:run:1")
print("Run 1:", entry)
# Expected: Run 1: {'status': 'complete', 'processed': 120}

# Check existence
print("Exists:", store.exists("agent:run:2"))   # True
print("Missing:", store.exists("agent:run:99")) # False

# Iterate all keys
for key in store.keys():
    print(key, "->", store.get(key))
```

--------------------------------

### Load Roster CSV Data with load_rosters

Source: https://context7.com/drqedwards/the_boy/llms.txt

Use `load_rosters` to read a CSV file, parse each row using `parse_record`, and obtain a list of typed roster dictionaries. This is the initial step for ingesting data into the knowledge graph.

```python
from pmll_agent.rosters import load_rosters

# Load the bundled mock dataset
rosters = load_rosters("data/rosters_mock.csv")

print(f"Loaded {len(rosters)} roster entries")
# Expected: Loaded N roster entries

# Inspect the first entry
if rosters:
    print("First entry keys:", list(rosters[0].keys()))
    print("Sample:", rosters[0])
```

--------------------------------

### Retrieve Node Attributes (Python)

Source: https://context7.com/drqedwards/the_boy/llms.txt

Retrieves attributes for a given node from the knowledge graph. Ensure the KnowledgeGraph is initialized and the node exists.

```python
node = kg.get_node("player_1")
print("player_1 attributes:", node)
```

--------------------------------

### Parse Raw CSV Row with parse_record

Source: https://context7.com/drqedwards/the_boy/llms.txt

Employ `parse_record` to transform a raw CSV row (as a dictionary) into a cleaned and type-coerced record. This function handles missing values and normalizes fields before data is added to the knowledge graph.

```python
from pmll_agent.parsers import parse_record

raw_row = {
    "id": "42",
    "name": "  Alice Example  ",
    "score": "9.7",
    "active": "true",
    "tags": "alpha,beta",
}

record = parse_record(raw_row)
print(record)
# Expected output (illustrative):
# {
#   "id": 42,
#   "name": "Alice Example",
#   "score": 9.7,
#   "active": True,
#   "tags": ["alpha", "beta"]
# }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.