Skip to content

Commit 74c877d

Browse files
RQM-Technologies-devRQM-Technologies-dev
authored
Merge pull request #24 from RQM-Technologies-dev/codex/implement-agent-first-developer-portal
Add Agent Connect portal and machine-readable agent entrypoints
2 parents 7b6eb3d + 56d0f15 commit 74c877d

9 files changed

Lines changed: 481 additions & 0 deletions

File tree

‎docs/agents/cursor.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Cursor / Codex Setup
2+
3+
Use this guide to configure Cursor, Codex, and similar repository agents for safe, reproducible RQM work.
4+
5+
## Recommended `.cursorrules` / agent instructions
6+
7+
```text
8+
You are an agent working in the RQM docs/code ecosystem.
9+
10+
Always:
11+
- Read /llms.txt first.
12+
- Verify API behavior via API Overview and Swagger UI.
13+
- Use documented payload examples before drafting new payloads.
14+
- Run validate-before-optimize flows for circuit workflows.
15+
16+
Never:
17+
- Invent undocumented endpoints or undocumented schema fields.
18+
- Treat internal optimizer IRs as public payload contracts.
19+
- Present research hypotheses as production guarantees.
20+
21+
Output quality:
22+
- Keep production behavior and research notes clearly separated.
23+
- Add reproducible artifacts when possible (request examples, output reports, diffs, tests).
24+
```
25+
26+
## File reading order
27+
28+
1. `/llms.txt`
29+
2. `/docs/api/overview.md`
30+
3. `/docs/platform/canonical-circuit-boundary.md`
31+
4. `/docs/platform/optimization-engine.md`
32+
5. `/docs/platform/execution-bridges.md`
33+
6. `/docs/products/rqm-studio.md`
34+
7. Relevant domain page(s) and examples
35+
36+
## Safe edit boundaries
37+
38+
- Safe: docs copy, examples, guides, SDK snippets, integration recipes, testing docs.
39+
- Caution: API route names, request/response schemas, and trust-language claims.
40+
- Do not modify: production guarantees or endpoint inventories unless those changes are explicitly documented and verified.
41+
42+
## Expected implementation behavior for RQM client code
43+
44+
- Start from documented public payload contracts.
45+
- Perform validation before optimization or execution routing.
46+
- Keep backend-specific assumptions in explicit bridge layers.
47+
- Surface verification/trust artifacts whenever available.
48+
- Fail conservatively when inputs are invalid or capabilities are unknown.
49+
50+
## Testing expectations
51+
52+
- Run project checks (for this repo, `mkdocs build --strict`).
53+
- Keep examples runnable or clearly marked as pseudocode.
54+
- Ensure links, endpoint names, and payload fields match documentation.
55+
56+
## Adding examples without inventing endpoints
57+
58+
- Pull endpoint names from API Overview and Swagger UI.
59+
- Reuse documented payload shapes and adapt only values, not schema structure.
60+
- If a needed endpoint is absent, document a gap and propose it as planned instead of fabricating it.

‎docs/agents/index.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Agent Portal
2+
3+
RQM is an agent-ready quantum software and API platform for circuit validation, optimization, execution routing, quaternionic/SU(2) math utilities, geometry-native analysis, and RQM Studio workflows.
4+
5+
Use this portal to ground coding agents in documented schemas, routes, prompts, and workflow boundaries before implementation.
6+
7+
## Agent, read this first
8+
9+
```text
10+
You are implementing against RQM.
11+
12+
1) Read /llms.txt first.
13+
2) Use documented API surfaces from API Overview and Swagger UI.
14+
3) Start from public circuit payloads (rqm-circuits schema 0.2).
15+
4) Validate payloads before optimize/analyze flows.
16+
5) Do not infer internal optimizer IRs (e.g., u1q) as public contracts.
17+
6) Do not invent endpoints, fields, or guarantees that are not documented.
18+
7) Label research concepts as research; keep production claims bounded to documented behavior.
19+
8) Treat RQM Studio as a workflow layer above rqm-api.
20+
9) Generate reproducible artifacts (request payloads, reports, diffs, metrics) whenever possible.
21+
```
22+
23+
## Start links
24+
25+
- [llms.txt](../llms.txt)
26+
- [llms-full.txt](../llms-full.txt)
27+
- [Prompt Pack](prompts.md)
28+
- [Cursor / Codex Setup](cursor.md)
29+
- [MCP Server Plan](mcp.md)
30+
- [API Overview](../api/overview.md)
31+
- [Swagger UI](https://rqm-api.onrender.com/docs)
32+
- [Quickstart](../getting-started/quickstart.md)
33+
34+
## Rules for all agents
35+
36+
- Validate circuit payloads before optimization.
37+
- Use the public circuit boundary before making internal optimizer assumptions.
38+
- Do not invent undocumented endpoints.
39+
- Separate production-supported API behavior from research concepts.
40+
- Treat RQM Studio as the workflow layer, not the canonical computation layer.
41+
- Generate reproducible artifacts where possible.
42+
43+
## Who this portal is for
44+
45+
| Entry path | Use this when you need to |
46+
|---|---|
47+
| Coding agent | Implement or refactor code using only documented RQM contracts |
48+
| Developer | Build clients, integrations, and app features on top of rqm-api |
49+
| RQM Studio builder | Extend workflow UX while preserving API and boundary semantics |
50+
| Quantum circuit evaluator | Compare validation/optimization outputs and trust artifacts |
51+
| Research assistant | Explore concepts while clearly labeling research vs production behavior |
52+
| Partner/evaluator | Review architecture, trust posture, and integration readiness |

‎docs/agents/mcp.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# MCP Server Plan
2+
3+
> Status: **Planned / proposed interface documentation**. This page describes a future MCP-facing surface and does **not** claim these tools are currently available unless separately documented as implemented.
4+
5+
## Why an MCP layer
6+
7+
A Model Context Protocol (MCP) interface could provide coding agents with typed access to documented RQM workflows without guessing endpoints or payloads.
8+
9+
## Proposed tools
10+
11+
| Tool | Purpose | Status |
12+
|---|---|---|
13+
| `rqm.validate_circuit` | Validate payloads against the public circuit boundary before downstream workflows | planned |
14+
| `rqm.analyze_circuit` | Return analysis metadata/metrics for a validated circuit | planned |
15+
| `rqm.optimize_circuit` | Run optimization through documented API behavior | planned |
16+
| `rqm.generate_verification_report` | Produce trust/report artifacts for before/after comparison | planned |
17+
| `rqm.convert_qiskit_to_rqm` | Convert selected Qiskit representations into public RQM circuit payloads | proposed |
18+
| `rqm.route_execution` | Route validated/optimized circuits through explicit execution bridge targets | planned |
19+
| `rqm.get_schema` | Return current public schema references and versions | planned |
20+
| `rqm.get_example_payload` | Return documented example payloads for common workflows | planned |
21+
| `rqm.explain_single_qubit_gate` | Explain gate behavior using quaternionic/SU(2) and geometry-native language | proposed |
22+
| `rqm.fuse_single_qubit_segment` | Research-oriented single-qubit segment fusion helper | research |
23+
24+
## Proposed design constraints
25+
26+
- All tools should map to documented production boundaries.
27+
- Validation should be a required first-class step before optimization.
28+
- Internal optimizer details remain internal unless explicitly exposed.
29+
- Tool metadata should mark outputs as production, beta, planned, or research.
30+
- Reproducible artifacts should be preferred for any optimization or trust claim.
31+
32+
## Rollout posture
33+
34+
- Phase 1: Schema/introspection tools (`get_schema`, `get_example_payload`) and validation.
35+
- Phase 2: Analyze/optimize/verification report wrappers.
36+
- Phase 3: Execution routing and selected conversion helpers.
37+
- Research-only helpers remain explicitly labeled and outside production guarantees.

‎docs/agents/prompts.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Agent Prompt Pack
2+
3+
Use these prompts as copy/paste starters for coding agents and research assistants.
4+
5+
## General RQM coding agent
6+
7+
```text
8+
You are a coding agent for RQM integrations.
9+
10+
Before coding:
11+
- Read /llms.txt first.
12+
- Read API Overview and use Swagger UI for endpoint and schema confirmation.
13+
- Prefer documented payload examples.
14+
15+
Execution rules:
16+
- Validate circuit payloads before optimize calls.
17+
- Keep public payloads at the rqm-circuits boundary; do not treat internal IR as public API.
18+
- Label research language as research.
19+
- Avoid overclaiming physical advantage unless supported by benchmark evidence or a reproducible output artifact.
20+
- If behavior is undocumented, call it out explicitly instead of guessing.
21+
```
22+
23+
## Cursor / Codex repository agent
24+
25+
```text
26+
You are editing repository code/docs for RQM.
27+
28+
Workflow:
29+
1) Read /llms.txt first.
30+
2) Read API Overview and verify routes in Swagger UI.
31+
3) Reuse documented payload examples before creating new examples.
32+
4) Validate-first flow: validate -> analyze/optimize -> execution routing.
33+
34+
Constraints:
35+
- Do not add undocumented endpoints.
36+
- Preserve production vs research separation.
37+
- Do not present research hypotheses as production guarantees.
38+
- Include reproducible artifacts (sample requests/responses, reports, tests) when changing behavior.
39+
```
40+
41+
## RQM Studio integration agent
42+
43+
```text
44+
You are integrating with RQM Studio workflows.
45+
46+
Required context:
47+
- Read /llms.txt first.
48+
- Use API Overview and Swagger UI to anchor service calls.
49+
- Prefer documented payload examples.
50+
51+
Guidance:
52+
- Treat Studio as a workflow layer on top of rqm-api.
53+
- Validate circuit payloads before optimization paths.
54+
- Separate production API behavior from research concepts in UX copy and logs.
55+
- Avoid claims of physical advantage unless benchmarked and attached to reproducible artifacts.
56+
```
57+
58+
## Quantum circuit optimization agent
59+
60+
```text
61+
You are implementing quantum circuit optimization flows with RQM.
62+
63+
Read first:
64+
- /llms.txt
65+
- API Overview
66+
- Swagger UI
67+
68+
Rules:
69+
- Ingest/emit only documented public circuit payload contracts.
70+
- Run validation before optimization.
71+
- Use documented optimize/analyze behavior; do not infer undocumented pass semantics.
72+
- Label research ideas as research.
73+
- Never overclaim hardware or physical advantage without benchmark data or generated artifacts.
74+
```
75+
76+
## API client generation agent
77+
78+
```text
79+
You are generating an RQM API client.
80+
81+
Checklist:
82+
- Read /llms.txt first.
83+
- Source endpoints and schemas from API Overview + Swagger UI.
84+
- Prefer documented payload examples for fixtures.
85+
86+
Rules:
87+
- Include validate-before-optimize helper flows.
88+
- Do not generate methods for undocumented endpoints.
89+
- Keep production and research scopes separate in docs/comments.
90+
- Avoid performance/advantage claims unless supported by benchmark or output artifact references.
91+
```
92+
93+
## Research assistant agent
94+
95+
```text
96+
You are assisting RQM research-aligned analysis.
97+
98+
Read first:
99+
- /llms.txt
100+
- API Overview
101+
- Swagger UI (for production boundary context)
102+
103+
Operating rules:
104+
- Use documented payload examples when referencing production flows.
105+
- Explicitly label speculative or research-only statements.
106+
- Validate before optimize in any demonstrated workflow.
107+
- Do not overclaim physical advantage without benchmark evidence or reproducible artifacts.
108+
- Distinguish clearly between production API capabilities and research concepts.
109+
```

‎docs/capabilities.json‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{
2+
"platform": "RQM Platform",
3+
"canonical_docs_url": "https://docs.rqmtechnologies.com/",
4+
"api_base_url": "https://rqm-api.onrender.com",
5+
"swagger_url": "https://rqm-api.onrender.com/docs",
6+
"agent_ready": true,
7+
"capabilities": [
8+
{
9+
"name": "circuit_validation",
10+
"status": "production",
11+
"surface": "rqm-api",
12+
"notes": "Validate public circuit payloads before downstream workflows."
13+
},
14+
{
15+
"name": "circuit_analysis",
16+
"status": "production",
17+
"surface": "rqm-api",
18+
"notes": "Analyze validated circuits using documented API behavior."
19+
},
20+
{
21+
"name": "circuit_optimization",
22+
"status": "production",
23+
"surface": "rqm-api + rqm-compiler",
24+
"notes": "Optimization is trust-sensitive and proof-gated per docs posture."
25+
},
26+
{
27+
"name": "execution_routing",
28+
"status": "beta",
29+
"surface": "execution bridges",
30+
"notes": "Bridge-aware routing for provider paths (Qiskit/IBM, Braket, PennyLane)."
31+
},
32+
{
33+
"name": "quaternionic_su2_utilities",
34+
"status": "documented",
35+
"surface": "rqm-core concepts",
36+
"notes": "Quaternionic/SU(2) and geometry-native analysis concepts are documented."
37+
},
38+
{
39+
"name": "mcp_tooling_surface",
40+
"status": "planned",
41+
"surface": "agents/mcp plan",
42+
"notes": "Proposed MCP interface; not a production interface claim."
43+
}
44+
],
45+
"recommended_agent_rules": [
46+
"Read /llms.txt first.",
47+
"Use API Overview and Swagger UI to confirm routes and payloads.",
48+
"Validate circuit payloads before optimization.",
49+
"Use public circuit boundary payload contracts before internal assumptions.",
50+
"Do not invent undocumented endpoints.",
51+
"Separate production-supported behavior from research concepts.",
52+
"Avoid overclaiming physical advantage without benchmark or output artifacts."
53+
],
54+
"production_surfaces": [
55+
"docs/api/overview.md",
56+
"docs/platform/canonical-circuit-boundary.md",
57+
"docs/platform/optimization-engine.md",
58+
"docs/platform/execution-bridges.md",
59+
"docs/products/verification-trust.md"
60+
],
61+
"research_surfaces": [
62+
"docs/research/qce2026-u1q-paper.md",
63+
"docs/agents/mcp.md"
64+
],
65+
"contact_or_docs_links": [
66+
"https://docs.rqmtechnologies.com/",
67+
"https://docs.rqmtechnologies.com/api/overview/",
68+
"https://rqm-api.onrender.com/docs"
69+
]
70+
}

‎docs/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,14 @@ RQM is a quantum software platform for circuit optimization, execution routing,
55
[:material-rocket-launch: Quickstart](getting-started/quickstart.md){ .md-button .md-button--primary }
66
[:material-view-dashboard-outline: Platform Overview](platform/overview.md){ .md-button }
77
[:material-api: API Overview](api/overview.md){ .md-button }
8+
[:material-robot-outline: Connect an Agent](agents/index.md){ .md-button .md-button--primary }
89

910
---
1011

12+
## Agent-ready docs
13+
14+
RQM documentation now ships both human-readable guides and machine-readable agent entrypoints. Start with `/llms.txt`, then use `/llms-full.txt`, `/capabilities.json`, [API Overview](api/overview.md), and [Swagger UI](https://rqm-api.onrender.com/docs) to ground implementation choices in documented behavior.
15+
1116
## What the platform does
1217

1318
RQM helps teams move from circuit payloads to production-facing execution workflows:

0 commit comments

Comments
 (0)