Pyrana Cortex v1.1 — Standalone UI User Guide
This guide covers every page of the Pyrana Cortex standalone UI. Each section describes what the page does, explains every column and field, and includes a screenshot of the live system.
Table of Contents
1. Dashboard
URL: /dashboard
The Dashboard is the Claims Evidence page. It tracks quantitative assertions made in the CORTEX V2 academic paper and patent against live system measurements, giving you a real-time view of whether the system is performing as specified.
Summary Bar
At the top of the page, a row of pill buttons shows how many claims fall into each status:
| Badge colour | Meaning |
|---|---|
| Blue | Good — within acceptable range |
| Green | Excellent — exceeds target |
| Yellow | Warning — approaching threshold |
| Red | Alert — threshold breached |
| Gray / Pending | No measurement data yet |
Claim Cards
Below the summary bar, cards are displayed in a responsive grid. Each card shows:
| Field | Description |
|---|---|
| Category label | One of: Latency, Retrieval Quality, Memory, Ambient, Scale |
| Source badge | Paper and/or Patent — which document the claim comes from |
| Claim title | The specific assertion being tracked |
| Status badge | Colour-coded to the summary bar above |
| Claimed value | What the paper or patent asserted |
| Latest value | What the live system measured most recently |
| Delta | Percentage difference between claimed and measured |
| Metric unit | Unit of measurement, e.g. ms, % |
Filtering Claims
Category tabs (Any / Latency / Retrieval Quality / Memory / Ambient / Scale) — click to filter the card grid. The active tab is underlined. The count next to each tab shows how many claims are in that category.
Source pills (Both / Paper / Patent) — restrict the view to claims from a specific source document. The count in each pill updates to reflect the active category filter.
Both filters can be combined — for example, "Latency" and "Paper" shows only latency claims sourced from the paper.
Claim Detail
Click any card to open the detail page at /dashboard/{claim_id}. The detail page shows the full claim text, measurement history, and baseline configuration.
Alert Thresholds
Hover over any card to reveal a gear icon in the top-right corner. Click it to open the Threshold Modal.
| Field | Description |
|---|---|
| Warning threshold | Value at which the card turns yellow. Leave blank to use ±10% of the target. |
| Alert threshold | Value at which the card turns red. Leave blank to use ±10% of the target. |
The direction of comparison ("≤ target" or "≥ target") is fixed by the claim type and cannot be changed here. Click Save to persist. The page refreshes automatically.
2. CxUs (Context Units)
URL: /cxus
CxUs are the atomic units of knowledge in the system. Each CxU contains a single, verifiable claim with optional supporting evidence and metadata. This page is the central list of all CxUs in the knowledge base.
Status Filter Tabs
The tabs at the top of the list filter by lifecycle state:
| Tab | Shows |
|---|---|
| All | Every CxU regardless of status |
| Active | CxUs included in query results |
| Draft | CxUs pending review — not yet in queries |
| Inactive | CxUs that have been deactivated |
| Versioned | CxUs superseded by a newer version |
List Columns
| Column | Description |
|---|---|
| CID | Content-addressable identifier (truncated). Click to open the CxU detail page. |
| Claim | The claim text, truncated to fit. Full text is on the detail page. |
| Status | Lifecycle state badge — Active (green), Draft (yellow), Inactive (gray), Versioned (blue). |
| Classification | Governance tier — see table below. |
| Version | Current version number shown as v1, v2, etc. |
| Sets | Set memberships. Up to 2 are shown; "…" indicates more exist. |
Classification Values
| Classification | Meaning |
|---|---|
| ABSOLUTE | Non-negotiable fact. Highest governance level — requires approval to modify. |
| REGULATED | Requires an approval workflow before activation. |
| CONTEXTUAL | Standard classification. No approval required. |
| TRIBAL | Organisation-specific knowledge not derived from documented sources. |
| DERIVED | Inferred or computed from other CxUs. |
Creating a CxU
Click New CXU (top right) to open the creation form.
| Field | Required | Description |
|---|---|---|
| Claim text | Yes | State the claim clearly and concisely. |
| Classification | No | Defaults to CONTEXTUAL. |
| Supporting context | No | Optional verbatim quotes or evidence that back the claim. |
| Entity ID | No | Scope the CxU to a specific entity (e.g. a product, regulation, or client). |
| Initial status | No | Start as DRAFT (default) or immediately ACTIVE. |
Click Create CXU to submit. On success you are taken to the new CxU's detail page.
CxU Detail Page
URL: /cxus/{cid}
The detail page shows the full CxU including:
- Full CID
- Complete claim text
- Supporting context — the verbatim quote(s) from the source document that back the claim
- Classification and status badges
- Activate / Deactivate button
- History button
Activating a DRAFT CxU — click Activate. The status changes to ACTIVE and the CxU becomes available in query results.
Deactivating an ACTIVE CxU — click Deactivate. The status changes to INACTIVE and the CxU is excluded from future queries.
Version conflicts — if another user has modified the CxU since you loaded the page, a conflict dialog appears. Reload the page before retrying.
Version history — click History to view the change log at /cxus/{cid}/history. Each entry shows the version number, date/time, status at that point, who made the change, and any recorded reason.
3. Sets
URL: /sets
Sets are named groupings of CxUs. They let you scope queries, organise knowledge by topic or domain, and designate certain CxUs as always-included (Rank 0).
Set List Columns
| Column | Description |
|---|---|
| Name | Set name (clickable link) with optional description below. |
| CXUs | Total number of CxUs currently in this set. |
| Rank0 | Number of always-included (Rank 0) CxUs in this set. "—" means none. |
| Created | Date the set was created. |
| Last Scan | Date of the most recent automated folder scan that targeted this set (see Sources). "—" means no scan has run or no folder is assigned. |
Creating a Set
Click New Set (top right). Enter the set name and an optional description, then submit.
Set Detail Page
URL: /sets/{name}
The detail page lists all CxUs that belong to the set. A search bar at the top of the member list lets you filter by CID or claim text.
| Column | Description |
|---|---|
| CID | Truncated content-addressable identifier. |
| Claim | Claim text, truncated. |
| Status | Lifecycle state badge. |
| Rank0 | Star icon — filled (★) means always-included; outline (☆) means standard member. |
Adding a CxU — enter the full CID into the input field and click Add.
Promoting to Rank 0 — click the outline star (☆) next to any member. It becomes filled (★). Rank 0 CxUs are always returned in query results for this set, regardless of relevance score.
Demoting from Rank 0 — click the filled star (★) to remove Rank 0 status. The CxU remains in the set but is no longer always-included.
Removing a CxU — click the trash icon next to the member. The CxU itself is not deleted — it is only removed from this set's membership.
4. Relationships
URL: /relationships
The Relationships page manages inferred connections between CxUs. Suggestions are generated automatically during document extraction based on co-occurrence and semantic similarity.
Pending Suggestions Table
When suggestions exist, the table shows:
| Column | Description |
|---|---|
| Source | Source CxU CID (truncated). |
| Relationship | Suggested relationship type, e.g. "supports", "contradicts". |
| Target | Target CxU CID (truncated). |
| Confidence | Model confidence as a percentage (0–100%). |
| Actions | Approve (green ✓) or Reject (red ✗) buttons. |
Approving — click ✓ to accept. The row is removed and the relationship is stored for use by graph retrieval strategies.
Rejecting — click ✗ to dismiss. The row is removed and the suggestion is not stored.
Empty State
When there are no pending suggestions, the page shows "No pending suggestions — Relationship suggestions appear here after document extraction." New suggestions are generated each time documents are extracted.
5. Agents
URL: /agents
The Agents page shows the live status of CORTEX agent processes and any knowledge gaps they have detected.
Agent Cards
Each CORTEX agent is displayed as a card showing:
| Field | Description |
|---|---|
| Name | Agent identifier with a coloured status dot. |
| Status | Current health state — Registered, Active, Healthy, or Degraded. |
| Type | Agent type identifier, e.g. RETRIEVAL_AGENT, LEARNING_AGENT, AMBIENT_AGENT, ORCHESTRATING_AGENT. |
Status dot colours:
| Colour | Meaning |
|---|---|
| Green | Active or Healthy — operating normally. |
| Blue | Registered — started but not yet processing. |
| Yellow | Degraded — running but with reduced capability. |
| Red | Error or unknown state. |
The four agents and their roles:
| Agent | Role |
|---|---|
| Retrieval Agent | Handles query execution, Q-value reranking, and cross-encoder reranking across the three retrieval strategies. |
| Learning Agent | Manages TEMPR memory and Q-value feedback loops — learns from query outcomes over time. |
| Ambient Agent | Runs proactive knowledge gap detection in the background based on recent query patterns. |
| Orchestrating Agent | Coordinates agent communication and task routing via the message bus. |
Knowledge Gaps
If the Ambient Agent has detected gaps, they appear below the agent cards with a yellow left border. Each gap describes an area where the knowledge base may be incomplete.
Refreshing
The page auto-refreshes every 30 seconds. Click Refresh to fetch the latest status immediately. The last-refreshed timestamp appears below the button.
6. Extract
URL: /extract
The Extract page lets you upload documents and extract CxUs from them automatically using the LLM extraction pipeline. Two modes are available via tabs.
Single File Tab
Use this tab to extract CxUs from one document at a time.
Supported formats: .pdf, .txt, .md, .docx, .doc, .csv
| Field | Description |
|---|---|
| Drop zone | Drag and drop a file here, or click to open a file picker. |
| Entity ID | Optional. Scope the extracted CxUs to a specific entity (e.g. a client name, product, or regulation identifier). |
| Upload & Extract button | Submits the file and starts extraction. |
Extraction phases:
| Phase | What you see |
|---|---|
| Uploading | Progress indicator while the file transfers. |
| Converting | The document is being converted to text. |
| Extracting | "extracting · N CXUs found" — the count updates as lenses complete. |
| Storing | CxUs are being written to the knowledge base. |
| Done | Final results shown — count of stored CxUs with quality grading scores if enabled. |
| Error | Error message in red with the failure reason. |
Results display — on completion the page shows:
- Quality Grading (if enabled): key point coverage (how many of the document's key points were captured) and document fidelity score (how well a document reconstructed from the CxUs matches the original).
- Extracted CxUs: list of all stored units, each showing the claim text, classification, and status.
Click Extract another to reset the form.
Batch / ZIP Tab
Use this tab to process multiple documents in one operation.
Supported formats inside the ZIP: .pdf, .txt, .md, .docx, .doc, .csv
| Field | Description |
|---|---|
| Drop zone | Drag and drop a ZIP file, or click to open a file picker. Supported file types are listed inside the zone. |
| Upload ZIP & Extract All button | Submits the archive and starts extraction for every supported file inside it. |
Progress display — while extraction runs, a file list appears with per-file status:
| Status | Colour | Meaning |
|---|---|---|
| queued | Gray | Waiting to start. |
| processing | Yellow | Currently being extracted. |
| completed | Green | Extraction finished successfully. |
| failed | Red | Extraction failed for this file. |
A summary line tracks overall progress: "{complete}/{total} complete · {failed} failed".
Click Upload another ZIP to reset after completion.
Timeout: Single-file extraction times out after approximately 3 minutes. Batch extraction times out after approximately 6 minutes. Large documents or archives with many files may approach these limits.
7. Query
URL: /query
The Query page lets you run ad-hoc semantic searches against the knowledge base to find relevant CxUs.
Search Form
| Field | Required | Description |
|---|---|---|
| Query | Yes | Natural language question or keyword phrase. Example: "What are the safety requirements for..." |
| Entity ID | No | Restrict results to CxUs scoped to a specific entity. Leave blank to search all entities. |
| Max results | No | Number of results to return — 1 to 20, default 10. |
Click Search to run. The button shows "Searching…" while the request is in flight.
Results
Results are listed in order of relevance. Each result card shows:
| Field | Description |
|---|---|
| Claim text | The CxU claim — bold. |
| Score | Relevance percentage — how closely this CxU matches the query. Green ≥ 70%, yellow 40–69%, gray below 40%. |
| Classification | Governance classification badge. |
| Status | Lifecycle state badge. |
| Sets | Set memberships — up to 2 shown. |
| Strategy | Which retrieval strategy returned this result: "template" (pre-built Cypher pattern), "edge-filter" (relationship-filtered Cypher), or "text2cypher" (free-form NLP-to-Cypher). Shown as "via {strategy}". |
| Rank 0 | Badge shown if this CxU is a Rank 0 member of one of the searched sets — meaning it was always-included regardless of score. |
Empty Results
If no CxUs match, the page prompts you to try different terms, remove the Entity ID filter, or check that relevant CxUs are in ACTIVE status.
8. Credentials
URL: /credentials
The Credentials page manages API keys used by external systems to authenticate with the A2A (Agent-to-Agent) endpoints.
Credential List Columns
| Column | Description |
|---|---|
| Name | Credential name (clickable). |
| Prefix | First few characters of the key followed by "…" — used to identify which key is which without exposing it. |
| Status | Active (usable) or Revoked (permanently disabled). |
| Rate limit | Requests per minute and requests per day, shown as "N/min · N/day". |
| Last used | Date the key was last used to make a request, or "Never". |
| Actions | Trash icon (active credentials only) — click to revoke. |
Creating a Credential
Click New Key (top right) to open the creation form.
| Field | Required | Default | Description |
|---|---|---|---|
| Name | Yes | — | A descriptive label for this key, e.g. "prod-integration-1". |
| Description | No | — | Optional notes about what this key is used for. |
| Rate limit / min | No | 60 | Maximum API calls per minute. |
| Rate limit / day | No | 10,000 | Maximum API calls per day. |
After clicking Create, a modal displays the full API key once only. Copy it before closing — the full key cannot be retrieved again. The modal requires you to click I have copied the key before it can be dismissed.
Important: If the key is lost, you must revoke it and create a new one. There is no key recovery mechanism.
Revoking a Credential
Click the trash icon on any active credential in the list, or click Revoke credential on the detail page. A confirmation dialog warns that the action is permanent. Revoked credentials immediately deny access to any system using that key.
Credential Detail Page
URL: /credentials/{id}
The detail page shows all credential metadata plus an inline editor for rate limits.
Editing rate limits — click Edit next to the rate limit display. Enter new values and click Save, or click Cancel to discard.
9. Sources
URL: /sources
The Sources page manages server-side folder monitoring. When a folder is registered, the system periodically scans it for new documents and automatically extracts CxUs, keeping the knowledge base in sync with the file system.
Monitored Folders Table
When folders are registered, the table shows:
| Column | Description |
|---|---|
| Path | Absolute server-side path to the monitored folder (truncated). |
| Set | The set into which extracted CxUs from this folder are stored. |
| CXUs | Number of CxUs extracted from documents in this folder. |
| Last Scan | Timestamp of the most recent scan. If the last scan encountered an error, the error message is shown here. "Never" means no scan has run yet. |
| Interval | Configured scan frequency in minutes. |
| Status | Healthy (green), Overdue (yellow), or Error (red) — see below. |
| Actions | Scan Now button and Delete (trash) button. |
Status logic:
| Status | When it shows |
|---|---|
| Error | The most recent scan ended with an error. |
| Overdue | No scan has run yet, or the last scan completed more than 2× the interval ago. |
| Healthy | Last scan completed within the expected window. |
Registering a Folder
Click Register Folder (top right) to expand the registration form.
| Field | Required | Description |
|---|---|---|
| Server path | Yes | Absolute path on the server running the Context Engine API — for example, /data/documents/contracts. This is a server-side path, not a path on your local machine. |
| Target set | Yes | The existing set to add extracted CxUs to. |
| Scan interval (minutes) | No | How often to scan — between 5 and 10,080 minutes. |
Click Register to save. Click Cancel to close without saving.
Empty State
When no folders are registered, the page shows "No folders registered — Register a server-side folder to begin automatic CXU extraction." This is the normal state for a fresh installation.
Manual Scan
Click the Scan Now button next to any registered folder to trigger an immediate scan outside the normal schedule. The icon spins during the scan. After the scan completes the page refreshes to show the updated timestamp and any errors.
Removing a Folder
Click the trash icon and confirm. The folder is removed from monitoring. Existing CxUs extracted from it remain in the set — they are not deleted.
10. Test Prompts
URL: /admin/test-prompts
The Test Prompts page has two tabs for evaluating query quality and monitoring CORTEX skill health.
Tab 1: Test Prompts
Use this tab to run test queries against the live knowledge base and inspect which CxUs are returned, at what score, and via which retrieval strategy.
| Field | Description |
|---|---|
| Load a preset | Dropdown of pre-configured test queries. Selecting one auto-populates the Query field and any associated set filters. |
| Query | Natural language query to run. Required. |
| Filter by set | Pill buttons for each available set. Click a pill to include only that set in the search. Leave all unselected to search across all sets. |
Click Run Query. Results are capped at 15.
Results display:
A summary line shows: "{total} results · {rank0} rank0 · searched: {sets} · {time}ms"
Results are split into two groups:
- Always-included (Rank 0) — CxUs returned unconditionally because they are marked Rank 0 in one of the searched sets.
- Query Results — remaining results ordered by relevance score.
Each result card shows:
- Claim text — click the chevron to expand and reveal the full CID
- Score badge — green ≥ 70%, yellow 40–69%, gray below 40%
- Rank 0 badge (if applicable)
- Set badges
- Strategy tag — which of the three retrieval strategies returned this result
- Classification badge
Tab 2: Skill Health
This tab shows the health status of all CORTEX agent skills — the learned behaviours that govern how agents retrieve and rank knowledge. Skills are created at runtime by CORTEX agents and evaluated using the /skill-eval CLI command.
When skills exist, the table shows:
| Column | Description |
|---|---|
| Skill | Skill name (bold) with category below. |
| Agent | The agent type that owns this skill. |
| State | Lifecycle state — draft, active, evaluated, tuned, or archived. |
| Health | Health flag — healthy (green), outgrowth_candidate (yellow), regression (red), not_evaluated (gray). |
| Pass % | Percentage of evaluation test cases this skill currently passes. "—" if not yet evaluated. |
| Delta pp | Change in pass rate since the previous evaluation, in percentage points. Green = improvement, red = regression. |
| Last eval | Date of the most recent evaluation run. |
Health flag meanings:
| Flag | Meaning |
|---|---|
| healthy | Skill is performing well against its test cases. |
| outgrowth_candidate | Skill may be ready to be promoted or expanded. |
| regression | Skill performance has declined — review recommended. |
| not_evaluated | Skill has never been evaluated. |
Lifecycle states:
| State | Colour |
|---|---|
| draft | Gray |
| active | Blue |
| evaluated | Indigo |
| tuned | Green |
| archived | Gray, strikethrough |
11. Admin
User Management
URL: /admin/users
The User Management page lists all users who have authenticated with the system. Users are created automatically on first login — they do not need to be pre-registered.
When users exist, the table shows:
| Column | Description |
|---|---|
| User | Display name (or email) as a clickable link. Email shown below the name. |
| Roles | Assigned roles shown as badges. "No roles" if none have been assigned yet. |
| Status | Active or Inactive. |
| Last access | Date of the most recent login, or "—" if the user has never logged in after account creation. |
User Detail Page
URL: /admin/users/{id}
Click any user name to open the detail page. All available roles are shown with their current assignment status.
| Role | Description |
|---|---|
| context_admin | Full access to knowledge base management — CxUs, sets, extraction, sources, and relationships. |
| company_admin | Organisational administrator — can manage users and credentials. |
| developer_support | Read-only access for debugging and support purposes. |
Assigning a role — click Assign next to an unassigned role.
Revoking a role — click Revoke (shown in red) next to an assigned role. If the user is the last company_admin, revocation is blocked with the message: "Cannot revoke: this is the last Company Admin. Assign another Company Admin first."
Navigation Reference
The left sidebar is present on every page and provides access to all sections:
| Item | URL | Purpose |
|---|---|---|
| Dashboard | /dashboard | Claims evidence tracking |
| CXUs | /cxus | Browse and manage Context Units |
| Sets | /sets | Manage named CxU groupings |
| Relationships | /relationships | Review and approve inferred CxU connections |
| Agents | /agents | Monitor CORTEX agent health |
| Extract | /extract | Upload documents and extract CxUs |
| Query | /query | Search the knowledge base |
| Credentials | /credentials | Manage A2A API keys |
| Sources | /sources | Configure automated folder monitoring |
| Test Prompts | /admin/test-prompts | Run test queries and view skill health |
| Admin | /admin/users | Manage users and roles |