Project mode

How it works

1. Simple is self-organizing. save-context writes nodes and relationships straight into the context graph, and the project ontology extends itself to fit. Nothing is declared first and no approval is in the way. The vocabulary grows by accretion, in whatever shape the data implies.
2. Advanced is deliberate. save-context fails validation outright. You propose a change to the ontology and then commit it, within an edit budget, and a commit may need a person's approval. Data still gets in, through the governed path rather than a direct write.
3. Each mode has two names. The interface says Simple and Advanced; the API says auto and manual. They are the same setting, and a person reporting a problem "in Advanced" and a log line with "mode":"manual" describe one project.

Simple removes friction, not governance.

In either mode every call is pinned to the caller's scope with the project filled in server-side, is policy-checked with a policy decision recorded, and is written to the tamper-evident audit record.

An agent in a Simple project can grow the vocabulary without asking anyone, and still cannot read another project, exceed the organization's quota or act without leaving a record.

Read the mode

Console: Settings, then Projects (/settings/projects) lists your projects, and editing one opens the "Project settings" dialog, which loads the current mode in the "Context Intelligence" control. API: GET /v1/projects/{projectId}/mode.

curl -sS -H "Authorization: Bearer $FABRIC_API_KEY" \
  https://fabric.wexa.ai/v1/projects/proj_abc/mode

const res = await fetch('https://fabric.wexa.ai/v1/projects/proj_abc/mode', {
  headers: { Authorization: `Bearer ${process.env.FABRIC_API_KEY}` },
})
console.log(await res.json())

import json, os, urllib.request

req = urllib.request.Request(
    "https://fabric.wexa.ai/v1/projects/proj_abc/mode",
    headers={"Authorization": f"Bearer {os.environ['FABRIC_API_KEY']}"},
)
print(json.load(urllib.request.urlopen(req)))

{ "project_id": "proj_abc", "mode": "auto", "ui_label": "Simple" }

The response carries both names, so it settles the vocabulary question. A project that has never been set resolves to Simple. Asking for another project's mode is refused whatever your role:

403 {"error":"forbidden","error_description":"project outside token scope"}

No endpoint lists the modes of every project in an organization. To audit your estate you need a token scoped to each project, one at a time. See the API reference for every response.

Change the mode

Console: Settings, then Projects (/settings/projects), edit the project, and in the "Project settings" dialog choose the "Context Intelligence" radio, Auto (Simple) or Manual (Advanced), then save. API: PUT /v1/projects/{projectId}/mode.

curl -sS -X PUT https://fabric.wexa.ai/v1/projects/proj_abc/mode \
  -H "Authorization: Bearer $FABRIC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"manual"}'

const res = await fetch('https://fabric.wexa.ai/v1/projects/proj_abc/mode', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.FABRIC_ADMIN_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mode: 'manual' }),
})
console.log(await res.json())

import json, os, urllib.request

req = urllib.request.Request(
    "https://fabric.wexa.ai/v1/projects/proj_abc/mode",
    data=json.dumps({"mode": "manual"}).encode(),
    method="PUT",
    headers={
        "Authorization": f"Bearer {os.environ['FABRIC_ADMIN_TOKEN']}",
        "Content-Type": "application/json",
    },
)
print(json.load(urllib.request.urlopen(req)))

{ "project_id": "proj_abc", "mode": "manual", "ui_label": "Advanced" }

Two checks run, in order: the project must be the one your token names, or 403 project outside token scope, and you must hold an administrator role, or 403 changing project mode requires an admin role.

The change is written through to the platform's own record of the project and recorded in the audit trail as project.mode.changed, kind: System, with your identifier, your role and the new mode. That record answers "who turned this off", subject to the retention caveat in audit and compliance.

The value that silently downgrades a project

The API accepts auto or simple and manual or advanced, in lower case. Anything else is not rejected. It is normalised to Simple and answered with 200. Executed against a project in Advanced:

PUT .../mode  {"mode":"turbo"}     -> 200 {"mode":"auto","ui_label":"Simple"}
PUT .../mode  {"mode":""}          -> 200 {"mode":"auto","ui_label":"Simple"}
PUT .../mode  {"mode":"Advanced"}  -> 200 {"mode":"auto","ui_label":"Simple"}

The third line is the dangerous one: Advanced with a capital A, the spelling the screen shows, turns Advanced off. The gateway has an error message for an unrecognised mode, but normalisation runs first and never leaves anything to reject.

• Send lower case, always, and prefer manual and auto.
• Read the response, never assume it. The ui_label in the reply is the mode you now have, not the mode you asked for.

What changes for your users

The mode changes what is possible, not what is visible, so people meet it as a call that used to work and now does not.

In Advanced, save-context is refused before anything is written:

422 {"error":"S4:validate-input",
     "error_description":"save-context is only available in Simple/auto mode;
       this project is in Advanced/manual mode — use create-ontology (proposal/commit)"}

If someone reports that saving context "broke", ask the project's mode first.

In Simple, an ordinary member's ontology commit returned 200 with "self_organized": true and "status": "committed", with no staging, approval or edit budget. In Advanced, a non-administrator's commit is staged, counts against the edit budget and is held:

{"status":"pending_approval",
 "approval":{"approval_id":"ar_6abb9f3c0b5ae73d6cdd6d41","resume_token":"hrt_ar_6abb9f3c0b5ae73d6cdd6d41.…"}}

An administrator committing in Advanced never creates an approval and returns 200 "status":"committed". Simple is the stricter mode in one place: since a vocabulary commit is never gated there, the data-classification rule is the only gate left, and it applies to administrators too.

These rows describe calls not made with an API key or SDK session. With either, an ontology commit is held for approval in both modes whatever the role, and so is save-context in Simple, while the project's write gate is on; it is off by default. See approvals.

Choose a mode

Stay in Simple when the project is exploratory, its members are not expected to reason about vocabulary, or nobody can work an approval queue. The trade is that the ontology grows by itself and nobody reviews the growth.

Move to Advanced when the vocabulary should stay deliberate, non-administrators need a second pair of eyes, or you want the edit budget as a brake. Typically that is once more than one team writes into the project, or once the context graph has consequences outside it.

The trade is that direct context writes stop and somebody must work the queue daily. It is the only way to get an approval gate on every non-administrator ontology commit; read approvals first.

The first choice is not final, but the vocabulary a Simple project has accumulated is not undone: switching to Advanced governs the next change, not the ones already made.

Switch safely

Simple to Advanced breaks working callers, so sequence it.

1. Find every caller of save-context in the project. After the switch they receive a 422. The save-context.executed audit events over the last window are the cheapest inventory, assuming a gateway that has not restarted.
2. Migrate them to create-ontology first, while both paths work.
3. Decide who works the approval queue and tell them. Approvals are overdue after 48 hours and expire unanswered after 96.
4. Flip the mode, lower case, and read the ui_label back.
5. Watch for a burst of pending approvals in the first day.

Advanced to Simple is quicker, with the reverse risks.

1. Drain the approval queue first. Held items do not migrate: a resume token belongs to an approval, and switching decides nothing already waiting.
2. Expect the gate to stop immediately. Commits by anyone go straight through and the edit budget stops applying. If the gate was a compliance control, one 200 and one audit line remove it.
3. Expect the ontology to self-organize again. Switching back does not undo what was added in Simple.

Related

• Project ontology: the commit path and the edit budget.
• Approvals: the queue Advanced mode creates.
• Project mode API reference: every response and status.