Package {pnotp}

pnotp: R client for the PnotP platform

Description

One account API key (pnotp_sk_..., minted in Studio -> Settings -> API keys) drives the whole platform from R:

Details

• LLM – pnotp_chat() for data-compliant chat with a retention receipt, pnotp_ellmer_chat() for tool calling and streaming through 'ellmer', pnotp_llm_pricing() for the public price list.

• Training – pnotp_project_create(), pnotp_model_create(), pnotp_train(), then pnotp_wait(), pnotp_progress() and plot().

• Deployments – pnotp_deploy_upload(), pnotp_deploy_open_source(), pnotp_predict(), pnotp_deployment_stats().

• Hosted agents – pnotp_agent_create(), pnotp_agent_publish(), pnotp_agent_run(), pnotp_agent_answer().

• Account – pnotp_set_key(), pnotp_me(), pnotp_credits().

• Help – pnotp_toby() asks PnotP's hosted assistant.

In 'RStudio', the Addins menu has "Chat with PnotP", "Explain selection with PnotP" and "Set PnotP API key".

Author(s)

Maintainer: Vicente Alonso Gallardo Montalva vicente@pnotp.ai

Authors:

• Vicente Alonso Gallardo Montalva vicente@pnotp.ai

Other contributors:

• PnotP [copyright holder, funder]

See Also

Useful links:

• https://pnotp.ai

• https://docs.pnotp.ai

Plot training metrics

Description

Draws each numeric per-epoch metric (train_loss, val_accuracy, val_rmse, ...) against the epoch, one panel per metric.

Usage

## S3 method for class 'pnotp_job_progress'
plot(x, ...)

Arguments

Value

x, invisibly.

Your account

Description

• pnotp_me() – who the key belongs to; the quickest "is my key working?" check.

• pnotp_credits() – credit balance and auto-refill state.

• pnotp_capabilities() – which platform features are switched on.

Usage

pnotp_me(client = NULL)

pnotp_credits(client = NULL)

pnotp_capabilities(client = NULL)

Arguments

Value

The API response, as a list.

Examples

## Not run: 
pnotp_me()$email
pnotp_credits()$balance_usd

## End(Not run)

RStudio addins

Description

Available from the 'RStudio' Addins menu once the package is installed (bind them to keys under Tools -> Modify Keyboard Shortcuts):

Usage

pnotp_addin_chat()

pnotp_addin_explain()

pnotp_addin_set_key()

Details

• Chat with PnotP (pnotp_addin_chat()) – a chat with the data-compliant LLM in the Viewer pane. Text selected in the editor is pre-filled as context. Each answer shows its receipt line. "Insert answer" writes the last answer on the line after your selection, never over it: its code blocks if it has any, otherwise the answer as ⁠#⁠ comments, so the script still runs. The conversation lives only in this R session.

• Explain selection with PnotP (pnotp_addin_explain()) – sends the selected code and prints an explanation in the console.

• Set PnotP API key (pnotp_addin_set_key()) – asks for the key (masked), sets it for the session and checks it against the API.

The chat needs the 'shiny' and 'miniUI' packages.

Value

pnotp_addin_chat() returns the last pnotp_chat_response (invisibly) when you press Done; pnotp_addin_explain() returns the response invisibly.

The final answer of an agent run

Description

A data-compliant run keeps a single final_answer event, which is preferred; otherwise the answer is the content of the last brain_turn.

Usage

pnotp_agent_answer(run, client = NULL)

Arguments

Value

The answer as a string, or NULL if the run has none yet.

Run a hosted agent

Description

Starts a run of the agent's current version. Follow it with pnotp_wait(), pnotp_progress(), pnotp_agent_steps() and pnotp_agent_answer().

Usage

pnotp_agent_run(
  agent,
  input,
  budget_usd = NULL,
  wait = FALSE,
  ...,
  client = NULL
)

Arguments

Value

A pnotp_agent_run.

Per-step meter of an agent run

Description

One row per brain turn or tool call, with its cost and latency.

Usage

pnotp_agent_steps(run, client = NULL)

Arguments

Value

The API response; a list of steps comes back as a data.frame.

Hosted agents

Description

A hosted agent is a brain (a reasoning model) driving a bounded tool-calling loop over the tools you attach, run on PnotP and metered against your credits. Create it, publish an immutable version with its model and tool allowlist, then run it with pnotp_agent_run().

Usage

pnotp_agents(client = NULL)

pnotp_agent(agent, client = NULL)

pnotp_agent_create(name, client = NULL)

pnotp_agent_publish(
  agent,
  model = "pnotp-compliant",
  system_prompt = "",
  tools = character(),
  budget_usd = NULL,
  client = NULL
)

Arguments

Details

With model = "pnotp-compliant" a run keeps no question, no reasoning and no loop state: only metered metadata and the encrypted final answer, held for 24 hours.

Value

pnotp_agents() returns a data.frame; the others the API response as a list.

Examples

## Not run: 
a <- pnotp_agent_create("Advisor")
pnotp_agent_publish(a, model = "pnotp-compliant", tools = "programs_db")
run <- pnotp_agent_run(a, "Which programs fit someone who loves maths?", wait = TRUE)
pnotp_agent_answer(run)

## End(Not run)

Account API keys

Description

Manage the pnotp_sk_... keys that authenticate this package. The raw key is returned only once, by pnotp_api_key_create().

Usage

pnotp_api_keys(client = NULL)

pnotp_api_key_create(name = "API key", client = NULL)

pnotp_api_key_revoke(key, client = NULL)

Arguments

Value

pnotp_api_keys() returns a data.frame; the others the API response.

Architecture graphs for common models

Description

Builders for the visual architecture graph pnotp_model_create() expects, so the package is usable end to end without hand-writing nodes and edges. Any hand-built graph (a nested list) works too.

Usage

pnotp_arch_image_classifier(num_classes = 2, channels = 3, size = 224)

pnotp_arch_tabular_classifier(n_features, num_classes = 2)

Arguments

Value

A nested list.

Examples

str(pnotp_arch_tabular_classifier(n_features = 4, num_classes = 3), max.level = 2)

Chat with the PnotP data-compliant LLM

Description

Calls POST /v1/llm/chat. PnotP itself stores neither the prompt nor the completion; the returned receipt is the durable audit artifact. Whether the whole path is zero-retention depends on the rail that served the call, and the receipt says so: read receipt$zero_retention and receipt$retention_basis rather than assuming it.

Usage

pnotp_chat(
  x,
  max_tokens = 256,
  temperature = 0.7,
  model = NULL,
  tools = NULL,
  tool_choice = NULL,
  file = NULL,
  image = NULL,
  audio = NULL,
  client = NULL
)

Arguments

Details

Calls are metered per token against your credits; an empty balance raises pnotp_insufficient_credits_error. See pnotp_llm_pricing() for rates.

For multi-turn tool calling and streaming, pnotp_ellmer_chat() drives the same models through 'ellmer'.

Value

A pnotp_chat_response: a list with completion, usage, model, receipt and, when the model called a tool, tool_calls. as.character() gives the completion text.

Examples

## Not run: 
out <- pnotp_chat("In one sentence, what is a p-value?")
out
out$receipt$zero_retention

pnotp_chat(data.frame(
  role = c("system", "user"),
  content = c("Answer in Spanish.", "What does dplyr::across() do?")
))

pnotp_chat("What is in this plot?", image = "figure.png")

## End(Not run)

Create a PnotP client

Description

A client holds the account API key, the API base URL and the request timeout. You rarely need one: every function takes client = NULL, which builds a client from the environment at call time, so a key set with pnotp_set_key() (or in ⁠~/.Renviron⁠) is picked up without restarting.

Usage

pnotp_client(api_key = NULL, base_url = NULL, timeout = 60)

Arguments

Details

A client created without a key can still call the public endpoints, such as pnotp_llm_pricing(). Authenticated calls fail with a pnotp_error that says how to set one.

Value

An object of class pnotp_client. Printing it masks the key.

Examples

cl <- pnotp_client(api_key = "pnotp_sk_example", base_url = "http://localhost:8000/v1")
cl

Training compute options

Description

CPU (free) and each GPU tier with its price. Pass a choice to pnotp_train(compute = , gpu = ).

Usage

pnotp_compute_options(client = NULL)

Arguments

Value

A list.

Deploy a model as a live endpoint

Description

• pnotp_deploy_upload() deploys a TorchScript .pt checkpoint.

• pnotp_deploy_open_source() deploys a catalog model (see pnotp_open_source_models()) with no training and no upload; extra arguments set its default inference parameters.

Usage

pnotp_deploy_upload(
  project,
  name,
  checkpoint,
  compliant = FALSE,
  client = NULL
)

pnotp_deploy_open_source(
  project,
  model_id,
  name = NULL,
  compliant = FALSE,
  ...,
  client = NULL
)

Arguments

Details

compliant = TRUE makes the endpoint data-compliant: the platform never persists request inputs, keeps error text out of monitoring, and every pnotp_predict() response carries a compliance receipt. It is a platform capability: when it is not enabled the call fails with a 409 (pnotp_api_error); check first with pnotp_compliance_available().

Value

The API response: for an upload, list(deployment = , board = ). Pass it straight to pnotp_predict().

Examples

## Not run: 
dep <- pnotp_deploy_upload(p, "prod", "model.pt", compliant = TRUE)
pnotp_predict(dep, "xray.jpg")

det <- pnotp_deploy_open_source(p, "yolox_s", confidence_threshold = 0.4)

## End(Not run)

Per-deployment inference keys

Description

Mint, list and revoke pnp_... keys that let an external consumer call one deployment with pnotp_predict(). The raw key is returned only once, by pnotp_deployment_key_create().

Usage

pnotp_deployment_keys(deployment, client = NULL)

pnotp_deployment_key_create(deployment, client = NULL)

pnotp_deployment_key_revoke(deployment, key_id, client = NULL)

Arguments

Value

The API response, as a list.

Manage deployments

Description

Manage deployments

Usage

pnotp_deployments(project, client = NULL)

pnotp_deployment(deployment, client = NULL)

pnotp_deployment_stats(deployment, window = "24h", client = NULL)

pnotp_deployment_pause(deployment, client = NULL)

pnotp_deployment_resume(deployment, client = NULL)

pnotp_deployment_delete(deployment, client = NULL)

pnotp_deployment_set_compliant(deployment, compliant = TRUE, client = NULL)

pnotp_compliance_available(client = NULL)

pnotp_private_available(client = NULL)

Arguments

Value

pnotp_deployments() returns a data.frame; the others the API response as a list. pnotp_compliance_available() and pnotp_private_available() return TRUE/FALSE, and FALSE when the capability probe itself fails.

Use PnotP models through 'ellmer'

Description

Returns an 'ellmer' chat object pointed at PnotP's OpenAI-compatible endpoint (POST /v1/chat/completions), authenticated with your account key. Everything 'ellmer' does then works against PnotP: multi-turn chat, streaming, tool calling with R functions (chat$register_tool()), and structured output (chat$chat_structured()).

Usage

pnotp_ellmer_chat(
  model = "pnotp-compliant",
  system_prompt = NULL,
  ...,
  client = NULL
)

Arguments

Details

The same retention terms as pnotp_chat() apply: PnotP stores neither prompt nor completion. 'ellmer' keeps the conversation in your R session only. The per-call receipt the endpoint adds to its response is not surfaced by 'ellmer'; use pnotp_chat() when you need to keep receipts.

Value

An 'ellmer' Chat object.

Examples

## Not run: 
chat <- pnotp_ellmer_chat(system_prompt = "You are a terse R expert.")
chat$chat("How do I pivot a data.frame longer?")

# Tool calling with an R function
chat$register_tool(ellmer::tool(
  function() format(Sys.time()),
  name = "now",
  description = "Current date and time."
))
chat$chat("What time is it?")

## End(Not run)

Errors raised by pnotp

Description

Every condition raised by the package inherits from pnotp_error. HTTP failures inherit from pnotp_api_error and carry the fields the backend publishes, so you never have to parse the message text:

Details

• status – the HTTP status code.

• detail – the backend's detail (a string, or a list for validation errors).

• code – a stable enum on LLM endpoints, e.g. "context_length_exceeded", "rate_limit_exceeded", "model_warming"; NULL when the endpoint does not publish one.

• retryable – FALSE means retrying cannot succeed; NULL if unknown.

• param – for parameter errors, the offending field.

• info – the full error object (e.g. max_context, tokens_in).

Examples

## Not run: 
tryCatch(
  pnotp_chat("hello"),
  pnotp_insufficient_credits_error = function(e) message("Add credits in Studio"),
  pnotp_api_error = function(e) if (isTRUE(e$retryable)) message("retry later")
)

## End(Not run)

Is a PnotP API key available?

Description

Is a PnotP API key available?

Usage

pnotp_has_key(client = NULL)

Arguments

Value

TRUE when the client (by default, the environment) has a key.

Training jobs

Description

List, fetch and control training jobs. Pausing or cancelling a running job is cooperative: the job stops at its next epoch boundary.

Usage

pnotp_jobs(client = NULL)

pnotp_job(job, client = NULL)

pnotp_job_pause(job, client = NULL)

pnotp_job_resume(job, client = NULL)

pnotp_job_cancel(job, client = NULL)

Arguments

Value

pnotp_jobs() returns a data.frame; the others a pnotp_job.

Models the LLM endpoints serve

Description

Calls the OpenAI-compatible GET /v1/models (authenticated).

Usage

pnotp_llm_models(client = NULL)

Arguments

Value

A data.frame with one row per model: id, description, vision, default, self_hosted, ...

Public LLM price list

Description

Calls GET /v1/llm/pricing, which needs no API key. Rates are per million tokens; metering_enabled says whether calls are billed today.

Usage

pnotp_llm_pricing(client = NULL)

Arguments

Value

A pnotp_pricing list (the raw response). Its print method shows one row per model in USD per million tokens.

Examples

pnotp_llm_pricing()

Model records

Description

A model record is a versioned model definition: an architecture graph, a dataset reference and a training method. Train it with pnotp_train().

Usage

pnotp_models(project, client = NULL)

pnotp_model(model, client = NULL)

pnotp_model_create(
  project,
  name,
  architecture,
  description = "",
  dataset_reference = NULL,
  training_method = NULL,
  client = NULL
)

pnotp_model_add_version(
  model,
  architecture,
  dataset_reference = NULL,
  training_method = NULL,
  client = NULL
)

pnotp_model_versions(model, client = NULL)

Arguments

Value

pnotp_model_create() and pnotp_model() return a pnotp_model_record; pnotp_models() and pnotp_model_versions() return data.frames; pnotp_model_add_version() returns the version.

Examples

## Not run: 
m <- pnotp_model_create(p, "cnn-v1", pnotp_arch_image_classifier(num_classes = 2))
pnotp_models(p)

## End(Not run)

The open-source model catalog

Description

Each entry carries its inference parameter spec and an available flag. The API answers 404 while the catalog is switched off.

Usage

pnotp_open_source_models(client = NULL)

Arguments

Value

A data.frame.

Run inference on a deployment

Description

Uploads file to POST /v1/deployments/{id}/predict. By default the call uses your account key. Pass a per-deployment key (pnp_...) as api_key to call as an external consumer; no account key is needed then.

Usage

pnotp_predict(deployment, file, ..., api_key = NULL, client = NULL)

Arguments

Details

On a compliant deployment the response carries a compliance block (compliant, retention, deployment_id, timestamp); keep it as the audit artifact.

Private (MPC) inference is not available from R yet; see the README.

Value

The prediction, as a list (e.g. predictions, class_names).

Examples

## Not run: 
pnotp_predict("dep_123", "xray.jpg")
pnotp_predict(dep, "street.jpg", confidence_threshold = 0.5)
pnotp_predict(dep, "xray.jpg", api_key = Sys.getenv("PNOTP_DEPLOYMENT_KEY"))

## End(Not run)

Projects

Description

A project groups model records and deployments.

Usage

pnotp_projects(client = NULL)

pnotp_project(project, client = NULL)

pnotp_project_create(
  name,
  task_type = "binary_image_classification",
  description = "",
  architecture = NULL,
  ...,
  client = NULL
)

Arguments

Value

pnotp_projects() returns a data.frame; the others return the project as a list.

Examples

## Not run: 
p <- pnotp_project_create("Chest X-ray", task_type = "binary_image_classification")
pnotp_projects()
pnotp_project(p)

## End(Not run)

Call any PnotP API route

Description

The low-level escape hatch every other function is built on. It sends the account key both as Authorization: Bearer (the management API) and as X-API-Key (inference), so one key authenticates every route, and turns any HTTP error into a typed condition (see pnotp_errors).

Usage

pnotp_request(
  method,
  path,
  query = NULL,
  body = NULL,
  multipart = NULL,
  auth = TRUE,
  api_key = NULL,
  client = NULL
)

Arguments

Value

The parsed JSON body as a list, a raw vector for non-JSON responses, or NULL for an empty body.

Examples

## Not run: 
pnotp_request("GET", "platform/capabilities")

## End(Not run)

Set the PnotP API key for this R session

Description

Stores the key in the PNOTP_API_KEY environment variable of the current session. Called with no argument in an interactive session, it asks for the key without echoing it (a masked dialog in 'RStudio').

Usage

pnotp_set_key(api_key = NULL)

Arguments

Details

To keep the key across sessions, add PNOTP_API_KEY=pnotp_sk_... to ⁠~/.Renviron⁠, for example with usethis::edit_r_environ(). This function never writes that file itself.

Value

TRUE, invisibly.

Examples

## Not run: 
pnotp_set_key()            # asks, masked
pnotp_set_key("pnotp_sk_...")

## End(Not run)

Ask Toby, PnotP's hosted assistant

Description

Asks a question in plain English about the platform, your deployments, or an error you just hit. Toby needs an API key and credits.

Usage

pnotp_toby(question, history = NULL, client = NULL)

Arguments

Details

Like the Python SDK's pnotp.help.toby(), this never raises: without a key, without credits, or without a network, it returns an offline answer (offline = TRUE) that says why and points at the local help.

Toby is told the question comes from this R package. Its built-in code reference is the Python SDK's, so check function names against the R help (?pnotp_chat) when it shows code.

Value

A pnotp_toby_answer: a list with text, offline, reason, proposed_action, and messages (the conversation so far, to pass as history).

Examples

## Not run: 
a <- pnotp_toby("How do I deploy a model and call it?")
a
pnotp_toby("And how do I make it data-compliant?", history = a)

tryCatch(pnotp_chat("hi"), pnotp_error = function(e) pnotp_toby(conditionMessage(e)))

## End(Not run)

Define a tool the LLM can call

Description

Builds an OpenAI-style function tool for pnotp_chat(). It takes care of the two JSON shapes R gets wrong by default: an empty properties is sent as {} (not ⁠[]⁠), and required is always an array, even with one name.

Usage

pnotp_tool(name, description, properties = list(), required = character())

Arguments

Value

A list ready to pass in tools = list(...).

Examples

weather <- pnotp_tool(
  "get_weather", "Current weather for a city.",
  properties = list(city = list(type = "string")),
  required = "city"
)
str(weather)

Train a model

Description

Submits a training run for a model record. Image models train on a .zip of class-named folders; tabular models train on a CSV, and you can pass a data.frame directly (it is written to a temporary CSV, uploaded, and deleted). Modality is detected from the model's architecture.

Usage

pnotp_train(
  model,
  dataset,
  version_id = NULL,
  epochs = 3,
  batch_size = 16,
  lr = 0.001,
  image_size = 64,
  target_column = "target",
  compute = NULL,
  gpu = NULL,
  wait = FALSE,
  client = NULL
)

Arguments

Value

A pnotp_job.

Examples

## Not run: 
m <- pnotp_model_create(p, "iris", pnotp_arch_tabular_classifier(n_features = 4, num_classes = 3))
job <- pnotp_train(m, iris, target_column = "Species", epochs = 20)
job <- pnotp_wait(job)
plot(pnotp_progress(job))

## End(Not run)

Wait for, refresh, or inspect a long-running object

Description

Generics for training jobs (pnotp_train()) and hosted agent runs (pnotp_agent_run()).

Usage

## S3 method for class 'pnotp_agent_run'
pnotp_wait(
  x,
  poll_interval = 1,
  timeout = 120,
  on_progress = NULL,
  quiet = FALSE,
  client = NULL,
  ...
)

## S3 method for class 'pnotp_agent_run'
pnotp_refresh(x, client = NULL, ...)

## S3 method for class 'pnotp_agent_run'
pnotp_progress(x, client = NULL, ...)

pnotp_wait(x, ...)

pnotp_refresh(x, ...)

pnotp_progress(x, ...)

## S3 method for class 'pnotp_job'
pnotp_wait(
  x,
  poll_interval = 2,
  timeout = NULL,
  on_progress = NULL,
  quiet = FALSE,
  client = NULL,
  ...
)

## S3 method for class 'pnotp_job'
pnotp_refresh(x, client = NULL, ...)

## S3 method for class 'pnotp_job'
pnotp_progress(x, client = NULL, ...)

Arguments

Details

• pnotp_refresh() re-fetches the object.

• pnotp_wait() polls until the status is succeeded, failed or cancelled, reporting status changes. Press Esc to stop waiting; the job itself keeps running.

• pnotp_progress() returns the live progress snapshot. For a training job, epochs is a data.frame with one row per finished epoch, and plot() draws its metrics.

Value

The refreshed object (pnotp_wait(), pnotp_refresh()), or a progress list (pnotp_progress()).