Write a plugin
A plugin is a folder in the Server's plugin directory, with plugin.py as its entry point. A plugin can:
| Capability | What it means |
|---|---|
| Generate its own Artifacts | Declare an Artifact family, read Sources, and write Artifacts of that family; callers read and tag them through the existing Artifact APIs |
| Present and search | Give each revision's default presentation, and optionally search, so the generic search API and Prepared Context can use the plugin's data |
| Support user changes | Implement create, update, merge, forget, and restore methods so the generic Artifact APIs work on the plugin's family |
| Define Source types | Declare the plugin's own Source types and Projections to record what users asked for, such as an upload |
| Provide APIs | Declare HTTP routes under /v1/plugins/<plugin name>/api/; core authenticates callers and forwards requests to the plugin |
| Provide Dashboard pages | Ship static pages that the Dashboard shows in a sandboxed iframe |
| Use dedicated storage and models | Keep the plugin's own data in separate storage that core allocates, and call the embedding and generation models Server configures |
Plugin code runs in the Server's Python environment and is treated as trusted code with the deployer's permissions. Load only plugins you trust.
Enable the plugin directory
Set the plugin directory and restart Server:
export POWERCONTEXT_SERVER_PLUGINS_DIR=/srv/powercontext/plugins
powercontext server run- Each subdirectory is a plugin, and its name is the plugin name (it starts with a lowercase letter and contains only
lowercase letters, digits, and
-). - Install the third-party libraries a plugin needs into the Server's Python environment, for example
uv pip install pypdf. Arequirements.txtin the plugin directory only informs deployers; Server does not install it. - Restart Server after changing a plugin. Server records a content fingerprint of the plugin directory when it loads and refuses to run plugin files that changed afterward, so old and new code never mix.
Check what loaded with administrator credentials:
curl -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8000/v1/pluginsEach plugin's status is loaded or failed; for failures, error gives the reason, such as an invalid declaration
field or a failed import.
A first plugin: turn text into notes
Create notes/plugin.py in the plugin directory:
from powercontext.plugins import (
ArtifactPlugin, ArtifactWriter, GenerateRequest, Inputs, Rendering, RenderRequest, SearchHit, SearchRequest,
SearchResult,
)
class Notes:
def __init__(self, ctx):
self.ctx = ctx
async def generate(self, request: GenerateRequest, writer: ArtifactWriter) -> None:
async with writer.transaction() as tx:
for source in request.sources:
text = source.projection["content"]
await tx.put(writer.stable_id(source.ref.source_id), content={"text": text}, source_refs=[source.ref])
async def render_artifact(self, request: RenderRequest) -> Rendering:
return Rendering(text=request.artifact.content["text"])
async def search_artifacts(self, request: SearchRequest) -> SearchResult:
query = request.search["query"]
page = await self.ctx.reads(request.scope_id).list(limit=200)
hits = [
SearchHit(ref=item.ref, text=item.content["text"])
for item in page.items
if query in item.content["text"]
]
return SearchResult(hits=hits[: request.search.get("limit", 10)])
async def setup(ctx):
return Notes(ctx)
plugin = ArtifactPlugin(
family="notes",
inputs=Inputs(source_types=("content",), projection="powercontext.text-evidence@1"),
on_sources=True,
setup=setup,
)After restarting Server, write a text Source; a few seconds later the plugin's Artifact can be read:
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/sources -d '{"content": "Deploys go to the east region first"}'
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes/$ARTIFACT_ID/rendering
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes/search -d '{"query": "east"}'This plugin has the basic parts of a plugin:
- The declaration
plugin = ArtifactPlugin(...)tells core which family the plugin owns, which Sources it consumes, and when it runs. - The factory
setup(ctx)returns the plugin object. Read the plugin's own settings from environment variables and open the resources it needs here. - Generation
generate(request, writer)receives a batch of new Sources and writes Artifacts. - Presentation
render_artifact(request)gives a revision's default presentation; it is required. - Search
search_artifacts(request)searches in the plugin's own way; it is optional. This example only matches substrings; a real plugin uses its own full-text or vector index.
The declaration
| Field | Meaning |
|---|---|
family | The Artifact family the plugin owns; it must not reuse a built-in family or another plugin's |
inputs | Inputs(source_types=..., projection=..., projections={...}, max_sources=50): the Source types consumed, the Projection each type arrives in, and the most Sources delivered at once. projection applies to every type; projections names one per type |
on_sources | Run when new Sources arrive |
schedule | Interval(seconds=...) or Cron(expression=..., timezone=...) to run on a schedule; without timezone, the time zone of the machine running Server applies. With neither schedule nor on_sources, the plugin has no background generation and need not implement generate; its Artifacts are written only by user changes and its own APIs |
scopes | Serve only these Scopes; required for plugins that set schedule but consume no Sources |
timeout_seconds, transaction_timeout_seconds | Time limits for one generation run and its write transaction |
change_timeout_seconds | Time limit for one user change, presentation, or search |
host_processes | The most host processes of this plugin in each Server process, 1 by default; deployers can override it |
definitions | The plugin's own Source Definitions; see "Define Source types" |
api | The plugin's APIs; see "Provide APIs" |
pages | Dashboard pages; see "Dashboard pages" |
setup | The factory; it must be an async function |
Server imports plugin.py and checks the declaration in a separate child process. If the import fails or the declaration
is invalid, the plugin is failed, without affecting Server or other plugins. After the host process calls setup, it
checks the required methods: a plugin without render_artifact, or one that declares schedule or on_sources without
generate, is also failed.
Methods of the plugin object:
| Method | Required | When it is called |
|---|---|---|
render_artifact | Yes | The presentation API |
generate | When schedule or on_sources is set | On schedule, or when new Sources arrive |
search_artifacts | No | The generic search API; Prepared Context sections that list the family |
create_artifact, update_artifact, merge_artifacts, forget_artifact, restore_artifact | No | The matching generic change APIs |
| Route handlers | When routes are declared | The plugin's own APIs |
Listing, reading revisions and history, governance state, and tags call no plugin method; core serves them directly.
Generate Artifacts
generate runs in a separate Worker process that Server starts, once per Scope:
request.scope_idis the call's Scope;request.sourcesare the Sources delivered, each with aref(its reference) and aprojection(its content in the declared Projection).- Put writes inside
async with writer.transaction() as tx:. The writes in the block commit in one transaction, together with the record that this batch of Sources was handled; if generation fails or times out, the batch is delivered again. - Do slow work such as model calls and file parsing outside the transaction, and only write inside it.
tx.put(artifact_id, content=..., source_refs=[...])writes a new revision and records its provenance insource_refs. Content identical to the current revision adds no revision, so repeated delivery never writes duplicate revisions.writer.stable_id(...)derives a stable ID from its inputs, so the same Source always writes to the same Artifact.- For an Artifact read outside the transaction with
writer.getand similar methods, core checks at write time whether it changed since: if its content was edited, or it was forgotten, restored, or merged, the write conflicts, the batch of Sources is delivered again later, and the plugin decides again from the new state. The plugin need not compare anything itself. - Other operations include
tx.set_lifecycle,tx.merge,tx.revert, andtx.set_tags; read current state withwriter.get,writer.list, andwriter.by_source.tx.revertandtx.set_lifecyclereturnArtifactChange:result.artifactis the target snapshot, whileresult.restoredandresult.retiredidentify other Artifacts affected by the same change. - Core records on each revision the plugin name and the content digest of the plugin code that wrote it, so revisions can be traced when several Servers load different plugin versions.
Generated Artifacts behave like built-in ones: read and tag them through the /v1/scopes/{scope_id}/artifacts/{family}
APIs.
Presentation and search
Core does not understand the content structure of plugin Artifacts and builds no index for them; plugins present and search their own families.
Presentation: render_artifact(request) receives one exact revision (request.artifact) and returns
Rendering(format="markdown", text=...); format can also be "text". Callers fetch it through the API below; without
revision, the current revision is used:
curl -H "Authorization: Bearer $TOKEN" \
"http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes/$ARTIFACT_ID/rendering?revision=2"The presentation of a revision should be stable, so callers can cache it by family, ID, revision, and plugin version.
Search: search_artifacts(request) receives the complete request of the generic search API (request.search, with
every field the caller sent, such as query, limit, mode, filters, and fusion; core handles include_scores and does
not pass it on), searches with the plugin's own
indexes, and returns SearchResult(hits=[SearchHit(ref=..., text=..., score=...)]):
- Raise
InvalidContentfor fields you do not support; the API returns 422 instead of silently ignoring them. - Core keeps only hits the caller may read that are still the current, active revision, in the plugin's order and with its scores.
textis the passage placed into agent context: part of the content or its presentation text.- When the plugin does not implement
search_artifacts, the generic search API and Prepared Context return 422 for the family.
Prepared Context: assembly.sections of POST /v1/context/prepare can list plugin families. Core calls
search_artifacts with the request's query and the section's limit; request.max_bytes is the request's byte budget.
Hits fill the context in section order and cite exact revisions. A section can carry search, whose fields reach the
plugin unchanged:
{
"scope_id": "team-a",
"query": "deploy region",
"assembly": {"sections": [{"family": "memory", "limit": 4}, {"family": "notes", "limit": 3, "search": {"mode": "hybrid"}}]}
}Support user changes
When the plugin object implements the methods below, the generic Artifact APIs work on the plugin's family; APIs whose method is missing return 422:
| Method | API |
|---|---|
create_artifact(request, writer) | POST /v1/scopes/{scope_id}/artifacts with body {"family": "<family>", "content": {...}} |
update_artifact(request, writer) | PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id} with If-Match |
merge_artifacts(request, writer) | POST /v1/scopes/{scope_id}/artifacts/{family}/merges |
forget_artifact(request, writer) | POST .../{artifact_id}/forget |
restore_artifact(request, writer) | POST .../{artifact_id}/restorations |
from powercontext.plugins import InvalidContent
class Notes:
async def update_artifact(self, request, writer) -> None:
if not request.content.get("text"):
raise InvalidContent("text is required", field="text")
async with writer.transaction() as tx:
await tx.put(request.artifact_id, content=request.content, expected_revision=request.expected_revision)
async def forget_artifact(self, request, writer) -> None:
async with writer.transaction() as tx:
await tx.set_lifecycle(request.artifact_id, "deprecated")- Core checks the caller's permissions and the revision before calling the method, and checks the caller's revision again when the write commits: if another write changed the Artifact in between, the request returns 409 (412 for content updates), so the plugin need not repeat the check. The method only validates content and makes its one agreed write.
- The response reports the revision this write committed, even if later writes have followed.
- Raising
InvalidContentreturns 422 with the message shown to the caller. - User changes record provenance as the person who made them, as edits of built-in Artifacts do. What is recorded is
the request's
contentas submitted: a method may treat it as a description of one change and write content computed from it, and the provenance still keeps what the caller submitted.
Define Source types
Sources record what happened and what users asked for. A plugin can define its own Source types, such as "a file was uploaded" or "some content was edited", and consume them in generation:
from pydantic import BaseModel
from powercontext.sources import Source, SourceMaterialization
class TicketInput(BaseModel): # the input when submitting
key: str
title: str
class TicketSource(Source): # the Source core stores
title: str
class TicketProjection: # what generate receives
name = "tickets.ticket"
version = "1"
source_class = TicketSource
output_class = TicketInput
def project(self, source, /):
return TicketInput(key=source.name, title=source.title)
class TicketDefinition:
name = "ticket" # the Source type name
version = "1"
input_class = TicketInput
source_class = TicketSource
projections = (TicketProjection(),)
async def resolve(self, value, /):
return TicketSource(
name=value.key, definition_version=self.version,
materialization=SourceMaterialization.CAPTURED, description="A ticket", title=value.title,
)
async def read(self, source, /):
return TicketProjection().project(source)
plugin = ArtifactPlugin(
family="tickets",
inputs=Inputs(source_types=("ticket",), projection="tickets.ticket@1"),
on_sources=True,
definitions=(TicketDefinition(),),
setup=setup,
)-
When the plugin loads, core registers these Source types. Callers can then write them through the generic Source API:
POST /v1/scopes/{scope_id}/sourceswith body{"source_type": "ticket", "content": {"key": "OPS-7", "title": "..."}}. The plugin validates the input and resolves it into a Source; invalid input returns 422. -
The plugin's own APIs submit them with
ctx.sources.submit(scope_id, "ticket", TicketInput(...)). -
A Source's
nameis its identity in the Scope; submitting the samenameagain yields the same Source. -
When a Source or Projection changes shape, raise the definition's
versionand setdefinition_versionto it inresolve. Core registers definitions by name and version, so old and new versions coexist, and stored Sources keep their old version's meaning. -
A plugin that consumes several Source types, each needing its own Projection, names them in
projections:Inputs(source_types=("upload", "edit"), projections={"upload": "kb.upload@1", "edit": "kb.edit@1"})In
generate, branch onsource.ref.source_type.
Provide APIs
A plugin can declare its own HTTP routes; handlers are async methods of the plugin object:
from pydantic import BaseModel
from powercontext.plugins import ApiError, ApiRequest, PluginApi, Route
class NewTicket(BaseModel):
scope_id: str
key: str
title: str
class Tickets:
def __init__(self, ctx):
self.ctx = ctx
async def open_ticket(self, request: ApiRequest) -> dict:
body: NewTicket = request.body
await self.ctx.require("scope.contribute", body.scope_id)
ref = await self.ctx.sources.submit(body.scope_id, "ticket", TicketInput(key=body.key, title=body.title))
return {"source_id": ref.source_id}
plugin = ArtifactPlugin(
...,
api=PluginApi(routes=(
Route(method="POST", path="/tickets", handler="open_ticket", access="authenticated",
body="json", request_model=NewTicket),
)),
)- Routes mount at
/v1/plugins/<plugin name>/api<path>, for examplePOST /v1/plugins/tickets/api/tickets. Callers use the same credentials as for every other API. accesssets the check core runs before calling the handler:authenticated: the caller must be signed in;scope.read/scope.contribute: the caller needs that permission on the Scope in the path parameter named byscope_param.
- In handlers,
ctx.require(action, scope_id)checks further permissions and makes the API return 403 when the caller lacks them;ctx.allowed(...)only answers true or false. When an API only accepts a request andgeneratechanges an existing Artifact later, first check the caller's write permission on that Artifact withctx.require("artifact.write", scope_id, artifact_id=...): the background write has no caller identity. This check covers only Artifacts of this plugin's family. - Reading and writing core data:
ctx.reads(scope_id)reads with the caller's permissions;ctx.writer(scope_id)andctx.sources.submit(...)work only for Scopes whosescope.contributewas confirmed earlier in the request (by the route'saccessor a priorctx.require). Changing an existing Artifact, including its tags, handles, and lifecycle, also needs the caller'sartifact.writeon that Artifact, as through the generic API; otherwise the API returns 403. - Writes in APIs do not record who did what. When you need that provenance, submit the operation as a Source, as in the
example above, and let
generatewrite the new revision referencing it. - To create a Scope, call
ctx.scopes.create(title=..., summary=..., idempotency_key=...); the caller needsserver.admin.ctx.scopes.list()returns the Scopes this plugin created that the caller can read.ctx.scopes.update(scope_id, expected_version=..., title=..., summary=...)changes a Scope this plugin created and also needsserver.admin; the API returns 404 when the Scope does not exist and 403 when another plugin or user created it. request.bodyis the validatedrequest_modelinstance,bytes, orNone, according tobody;request.path_params,request.query, andrequest.callerare the path parameters, query parameters, and caller.- Return a Pydantic model or a dict for JSON,
BinaryResponse(content=..., content_type=..., filename=...)for a file, orNonefor 204. RaiseApiError(status, code, message)for a 4xx error. - Request body limits default to 1 MiB for JSON and 32 MiB for binary bodies. A route can declare
max_body_bytes, which never exceeds the deployer'sPOWERCONTEXT_SERVER_PLUGIN_API_MAX_BODY_BYTES. Core returns 413 without calling the plugin when a body is too large. - Each call is bounded by
timeout_seconds(30 seconds by default) and returns 504 when it runs over.
APIs, presentation, search, and user-change methods run in host processes. Each plugin has its own group of host
processes and shares none with other plugins: the first starts once the plugin loads and always stays; another starts
while every process is busy and requests queue, up to host_processes; extra processes stop after 5 idle minutes. The
factory setup(ctx) runs once in each host process, and the plugin object serves every request that process receives, so
do not assume all requests reach the same process.
- A host process handles several requests at once on one event loop. When a call runs past its time limit, core cancels only that request (its write transaction rolls back) and returns 504; other requests in the process are unaffected.
- Blocking the event loop keeps cancellation from taking effect and also stops the host process's heartbeat. Five seconds
after the heartbeat stops, core terminates the process: requests that passed their own time limit before then return
504, requests still in flight at termination (including the one that blocked) return 503, and the process restarts
after a backoff. Put CPU-heavy or synchronously blocking code in
await asyncio.to_thread(...), and leave work that takes minutes to the backgroundgenerate. - In Prepared Context, a plugin section is left out when the plugin is unavailable (a timeout, no available host process, or a failed search); the receipt records the family's failed search, and the other sections are returned as usual.
Dedicated storage and models
from sqlalchemy import text
async def setup(ctx):
engine = ctx.storage.engine() # points only to this plugin's storage
async with engine.begin() as connection:
await connection.execute(text("CREATE TABLE IF NOT EXISTS notes_index (id TEXT PRIMARY KEY, body TEXT)"))
return Notes(ctx)ctx.storage.engine()returns an async SQLAlchemy engine for this plugin's storage only, on the Server's database backend and with its connection settings:plugins/<plugin name>.sqlite3in the data directory on SQLite deployments, and a database namedpowercontext_plugin_<plugin name>(with-replaced by_) on the same tenant or instance on OceanBase and seekdb deployments.ctx.storage.backendnames the backend (sqlite,oceanbase, orseekdb) so the plugin can choose its table definitions and indexes. The plugin owns its tables and migrations; core never reads or backs up this storage.- On OceanBase and seekdb, core creates the database when the plugin loads and reuses an existing one. When the Server's
database login cannot create databases, the deployer creates it and grants access beforehand. If the database is
missing and cannot be created, or its name exceeds 64 characters (a plugin name longer than 44), the plugin still
loads, and
ctx.storage.engine()raises an error that states the reason. - This storage is outside core's transactions. Store large content such as files and vectors under its content digest and reference the digest from Artifacts: retried writes and rolled-back transactions then leave only unreferenced records, never Artifacts pointing at the wrong data.
- The storage belongs to the whole plugin and is not split by Scope. Partition data by
scope_idand confirm on reads that data belongs to the request's Scope. ctx.modelsholds the models Server configures, orNonewhen it configures neither:await ctx.models.embed(["..."])returns vectors;ctx.models.embedding_dimensionis their dimension;await ctx.models.generate([ChatMessage(role="user", content="...")], max_tokens=500)returns generated text;- check
embedding_availableandgeneration_available; calling a model Server lacks raisesModelUnavailable.
Dashboard pages
Plugins that declare APIs can ship pages:
plugin = ArtifactPlugin(..., pages=PluginPages(directory="ui", entry="index.html", title={"zh": "工单", "en": "Tickets"}))ui/index.html loads the client script core provides and calls the plugin's APIs through it:
<script src="/dashboard/plugins/_client.js"></script>
<script>
const client = powercontextPluginClient();
const { language, theme, scopeId } = await client.context();
const response = await client.request("POST", "/tickets", { json: { scope_id: scopeId, key: "OPS-7", title: "Disk full" } });
if (response.ok) console.log(response.json);
</script>- The page appears in the Dashboard's side navigation at
/dashboard/plugins/<plugin name>. - The page runs in a sandboxed iframe without the user's session; the Dashboard forwards its requests as the current user, only to routes the plugin declares and to the generic Artifact API of the plugin's family.
client.request(method, path, options)acceptsjson,body(such as a file'sArrayBuffer),contentType, andquery, and returnsstatus,ok,json,blob, andfilename.client.artifacts(method, path, options)calls the generic Artifact API of this plugin's family, with no route to declare.pathfollows/v1/scopes/{scope_id}/artifacts/{family}: an empty string lists (GET) or creates (POST),/{artifact_id}reads or edits,/{artifact_id}/forgetforgets, and so on.optionsalso takesscopeId(the page's current Scope by default) andifMatch, and the result also hasetagandlocation. Permissions, version checks, and provenance are the same as calling the generic API directly, and the page cannot name another family.- Build the page as a single-page app: after the page navigates, the Dashboard stops forwarding and asks the user to reopen
it. Browser dialogs such as
alertandconfirmare unavailable in the sandbox. - Pages are static files only (HTML, JavaScript, CSS, images, fonts), up to 5 MiB each; scripts may come only from the
plugin's own directory and
/dashboard/plugins/_client.js.
Troubleshooting
| Symptom | What to do |
|---|---|
The plugin is failed in /v1/plugins | Read error: for import failures, check that dependencies are installed in the Server environment; for a missing required method, add it |
| APIs return 503 | The host process is starting or restarting, or was terminated because its event loop was blocked; check the Server log for plugin errors |
APIs return 504 plugin_timeout | The call ran past its time limit; move slow work into asyncio.to_thread or generate, or raise the limit |
APIs return 500 plugin_error | A handler raised an unhandled exception; the Server log records its type |
| Workers stop running after a plugin change | Plugin files changed while Server was running; restart Server |
| Generated Artifacts do not appear | Check GET /v1/plugins/<plugin name>/scopes for Scopes with pending Sources |
Current limits
- Updating a plugin requires a Server restart; hot reload is not available yet.
- Deployers install plugin dependencies into the Server environment by hand.
- Plugin code has the Server's permissions; host processes and Workers isolate failures, not untrusted code.

