arango-sparql-py 0.2.0__tar.gz

arango_sparql_py-0.2.0/.cursor/rules/000-project-context.mdc

@@ -0,0 +1,61 @@
+---
+description: Always-on project identity and hard guardrails for arango-sparql-py
+alwaysApply: true
+---
+
+# Project: arango-sparql-py
+
+You are an expert Semantic Web and ArangoDB developer building `arango-sparql-py`,
+a Python microservice that transpiles SPARQL 1.1 queries into ArangoDB AQL.
+
+This project is the modernization of the legacy JavaScript Foxx service
+`arango-sparql` and the sister project to `arango-cypher-py`.
+
+## Hard guardrails (non-negotiable)
+
+1. **DO NOT use ANTLR or roll a custom SPARQL parser.** Always use
+   `rdflib.plugins.sparql.parser.parseQuery()` to obtain the SPARQL AST
+   (Algebra), then walk it with a Python visitor.
+2. **Never hand-concatenate AQL.** All AQL must be emitted via the
+   parameterized AQL query builder (mirroring `arango-cypher-py`'s pattern)
+   so bind variables are the only injection-safe path.
+3. **Do not invent translation rules.** The semantic mapping of SPARQL
+   constructs to AQL must be ported from the legacy
+   `references/arango-sparql/src/lib/*-translator.js` files. When in doubt,
+   read the JS first and translate the *behavior*, not the syntax.
+4. **Match `arango-cypher-py` architecture.** FastAPI app factory, route
+   modules, pydantic request/response models, multitenancy guards, `uv` +
+   `pyproject.toml` dependency management, and `pytest` harness layout must
+   be structurally identical so a developer who knows one repo can read the
+   other immediately.
+
+## Reference repos (sibling projects)
+
+When you need to understand a pattern, consult these — they are symlinked
+into `references/`:
+
+- `references/arango-cypher-py/` — the architecture template (FastAPI,
+  nl2cypher, eval harness, UI shell, pyproject layout).
+- `references/arango-sparql/` — the legacy Foxx service whose SPARQL→AQL
+  translation semantics are being ported (read-only source of truth for
+  query translation behavior).
+- `references/arango-schema-mapper/` — generates the OWL/Turtle ontology
+  this service consumes for URI→collection resolution.
+
+## Directory anchors
+
+- `arango_sparql/` — Python package (mirror of `arango_cypher/`).
+- `arango_sparql/service/` — FastAPI app + routes (mirror of
+  `arango_cypher/service/`).
+- `arango_sparql/nl2sparql/` — NL→SPARQL pipeline (mirror of
+  `arango_cypher/nl2cypher/`).
+- `tests/` — pytest harness; `tests/w3c/` is the SPARQL DAWG runner
+  (analog of `arango-cypher-py/tests/tck/`).
+- `ui/` — Vite + React + TypeScript frontend (mirror of
+  `arango-cypher-py/ui/`).
+
+## Task management
+
+Always update the project todo list when starting non-trivial work. Refer
+to the file you are about to change with the Read tool before editing —
+no blind edits.

arango_sparql_py-0.2.0/.cursor/rules/100-backend-python.mdc

@@ -0,0 +1,86 @@
+---
+description: Backend Python conventions — FastAPI service, rdflib parsing, AQL builder, OWL schema mapping
+globs:
+  - "arango_sparql/**/*.py"
+  - "main.py"
+  - "scripts/**/*.py"
+---
+
+# Backend Python rules
+
+## Tooling
+- Dependency manager: **`uv`** (no `poetry`, no bare `pip`). Add deps with
+  `uv add ...`; update lock with `uv lock`.
+- Python: **>=3.11**, `from __future__ import annotations` at top of every
+  module.
+- Lint/format: **`ruff`** with `line-length = 110`, `target-version = "py311"`.
+- Typing: prefer PEP 604 unions (`str | None`), `dataclass` for plain data,
+  `pydantic.BaseModel` for any HTTP request/response or external contract.
+
+## SPARQL parsing — always rdflib
+- Entry point for parsing:
+  `from rdflib.plugins.sparql.parser import parseQuery`
+  followed by `from rdflib.plugins.sparql.algebra import translateQuery` to
+  obtain the Algebra tree.
+- The translator is a **visitor over the Algebra**, not over the parse
+  tree. Every Algebra node type (`BGP`, `Project`, `Filter`, `LeftJoin`,
+  `Union`, `Slice`, `OrderBy`, `Distinct`, `Extend`, `Group`, `AggregateJoin`,
+  `Service`, …) gets one `visit_<NodeType>` method.
+- Unknown nodes must raise a typed error (e.g. `UnsupportedSparqlError`) —
+  never fall through silently.
+
+## AQL emission — always the builder
+- All AQL strings flow through the AQL query builder (port of
+  `references/arango-sparql/src/lib/aql-query-builder.js`). Never concatenate
+  AQL with `+` or f-strings outside the builder.
+- Variables from SPARQL bind to AQL bind variables (`@var`). Literal values
+  always become bind variables; never inline them into the AQL string.
+- The builder owns aliasing — do not generate FOR-loop variable names
+  manually; ask the builder for a fresh alias.
+
+## OWL / schema mapping
+- Load the ontology produced by `arango-schema-mapper` into a single
+  `rdflib.Graph` at app startup; cache by ontology hash.
+- URI → physical collection/edge/property resolution goes through one
+  `SchemaResolver` class. SPARQL visitors call the resolver; they never
+  reach into the graph directly.
+- Treat the OWL graph as immutable after load. If schema can change at
+  runtime, version the resolver and swap atomically.
+
+## FastAPI service shape (mirror `arango_cypher/service/`)
+- `app.py` owns the `FastAPI(...)` instance, CORS middleware, observability
+  install, and import-time guards. Route modules import `app` from here.
+- `models.py` holds every pydantic request/response model and the
+  `_MAX_*` length constants (e.g. `_MAX_SPARQL_LENGTH`,
+  `_MAX_AQL_LENGTH`, `_MAX_TURTLE_LENGTH`). All user-controlled string
+  fields use `Field(..., max_length=_MAX_*)`.
+- `security.py` collects sessions, rate limit, SSRF guard, error redaction,
+  pydantic 422 handler.
+- `routes/` — one module per resource: `sparql.py`, `nl.py`, `schema.py`,
+  `owl.py`, `connect.py`, `health.py`. Each route uses
+  `Depends(_check_compute_rate_limit)` and `Depends(_get_session)` exactly
+  like the Cypher service.
+- `mapping.py` adapts incoming JSON mapping payloads to the in-memory
+  schema/resolver objects.
+- Multitenancy guards: every endpoint that runs AQL must enforce a
+  `TenantContext`; physical-tenant collection rewriting happens in one
+  place, not scattered.
+
+## Errors
+- Define a typed error hierarchy:
+  `SparqlError` → `SparqlParseError`, `UnsupportedSparqlError`,
+  `SchemaResolutionError`, `AqlEmitError`. Each carries a stable
+  `code` string for the HTTP layer to surface.
+- Service layer maps `SparqlError` → `HTTPException(status_code=422)` with
+  `{"error": <sanitized>, "code": <code>}`; all other exceptions are
+  500s after sanitization.
+
+## Logging
+- Module-level `logger = logging.getLogger(__name__)`. Do not use
+  `print()`. Correlation-ID middleware (mirror Cypher's
+  `CorrelationIdMiddleware`) tags every request log line.
+
+## Forbidden
+- ANTLR runtime, hand-written SPARQL parsers, raw AQL string
+  concatenation, top-level mutable globals (other than the FastAPI `app`,
+  module-level loggers, and the immutable schema cache).

arango_sparql_py-0.2.0/.cursor/rules/200-testing.mdc

@@ -0,0 +1,62 @@
+---
+description: Testing rules — pyoxigraph as ground truth, W3C DAWG harness, golden tests, eval harness
+globs:
+  - "tests/**/*.py"
+  - "conftest.py"
+---
+
+# Testing rules
+
+## Frameworks
+- `pytest` is the only test runner. Use `pytest -q -ra` locally.
+- Markers (declared in `pyproject.toml`):
+  - `integration` — requires a running ArangoDB.
+  - `w3c` — W3C SPARQL 1.1 DAWG harness.
+  - `cross` — cross-validation against `pyoxigraph` as the reference
+    triplestore (the SPARQL analog of the Cypher project's `cross`/Neo4j
+    marker).
+  - `eval` — NL→SPARQL eval harness (slow; gated behind env var).
+
+## Reference triplestore — `pyoxigraph`
+- Use `pyoxigraph` as the **embedded W3C-compliant ground truth** for
+  every SPARQL semantics test. It runs in-process (no Docker) so tests
+  stay fast.
+- Cross-validation pattern: load the same RDF data into `pyoxigraph` and
+  into ArangoDB (via the schema-mapper-defined mapping), execute the same
+  SPARQL against `pyoxigraph` directly and against ArangoDB via
+  `arango-sparql-py`'s transpiled AQL, then assert the result bindings
+  match — order-insensitive for SELECT, set-equality for ASK/CONSTRUCT.
+- Helpers live in `tests/helpers/oxi.py` (loader + binding-equality
+  comparator). Do not call `pyoxigraph` directly from individual test
+  files.
+
+## W3C DAWG harness (mirror `tests/tck/`)
+- Vendor the W3C SPARQL 1.1 Evaluation tests under
+  `tests/w3c/data/` (gitignored if large; provide a `make fetch-w3c`
+  script).
+- `tests/w3c/runner.py` enumerates manifests (`mf:Manifest`) via `rdflib`
+  and yields `(query_file, data_files, expected_results)` tuples.
+- Each test is a single pytest case parametrized over the manifest entry
+  IRI so failures point back to the W3C test name.
+- Maintain a `tests/w3c/SKIP_REASONS.md` listing intentionally skipped
+  tests with the reason (analog of the TCK skip file).
+
+## Golden tests for translation
+- Pattern: one test file per SPARQL feature — e.g.
+  `test_translate_optional_goldens.py`, `test_translate_filter_goldens.py`.
+- Inputs and expected AQL/bind_vars live in YAML next to the test file
+  (mirror Cypher's golden YAML format). Updates require explicit human
+  review — never auto-regenerate goldens in CI.
+
+## NL→SPARQL eval harness (mirror `tests/nl2cypher/eval/`)
+- `tests/nl2sparql/eval/runner.py` consumes `corpus.yml` + `configs.yml`,
+  produces JSON + Markdown reports under `tests/nl2sparql/eval/reports/`
+  (gitignored — only `baseline.json` is checked in as the regression gate).
+- The runner accepts any `LLMProvider`, so unit tests use a scripted mock
+  and CI uses the real provider only on demand.
+
+## Forbidden
+- Calling LLM providers from non-`eval`-marked tests.
+- Hitting a real ArangoDB from non-`integration`-marked tests.
+- Comparing AQL strings character-for-character outside the goldens —
+  semantic equivalence is what matters everywhere else.

arango_sparql_py-0.2.0/.cursor/rules/300-nl2sparql.mdc

@@ -0,0 +1,48 @@
+---
+description: NL→SPARQL pipeline rules — Turtle prompts, providers, fewshot, tenant guardrails
+globs:
+  - "arango_sparql/nl2sparql/**/*.py"
+  - "tests/nl2sparql/**/*.py"
+---
+
+# NL→SPARQL rules
+
+## Structure (mirror `arango_cypher/nl2cypher/`)
+- `_core.py` — pipeline orchestrator and `NL2SparqlResult` dataclass.
+- `providers.py` — `LLMProvider` protocol + concrete `OpenAIProvider`,
+  `AnthropicProvider`, plus the test-only `ScriptedProvider` mock.
+- `fewshot.py` — BM25-backed few-shot index over a curated corpus.
+- `tenant_guardrail.py` + `tenant_scope.py` — same multitenancy posture
+  as Cypher: physical-tenant collection rewriting and prompt-side scope
+  hints, enforced before the AQL ever runs.
+- `entity_resolution.py` — optional ER hook (mirrors Cypher's).
+- `_aql.py` — final AQL emission step (translates the LLM's SPARQL
+  through the same parser/visitor/builder pipeline the `/translate`
+  endpoint uses; never asks the LLM for AQL directly).
+
+## Prompt construction
+- Always provide the **OWL ontology in Turtle (`.ttl`)** as the schema
+  context. LLMs read Turtle far better than JSON-LD or XML. Generate
+  Turtle from `arango-schema-mapper`'s OWL output.
+- Prompt header: pin the SPARQL dialect (`SPARQL 1.1`), forbid vendor
+  extensions, require fully-qualified IRIs (no bare prefixes the model
+  invents), and constrain output to a fenced ```sparql``` block.
+- Few-shot examples come from the BM25 index over a curated YAML corpus;
+  never inline more than 3 shots — token budget is real.
+
+## Result type
+- `NL2SparqlResult` carries: `sparql`, `explanation`, `confidence`,
+  `method` (`"llm"` | `"rule_based"` | `"cached"`), `schema_context`,
+  `prompt_tokens`, `completion_tokens`, `total_tokens`, `cached_tokens`,
+  `retries`. Match Cypher's `NL2CypherResult` field-for-field where the
+  semantics carry over — easier cross-repo telemetry.
+
+## Caching / corrections
+- Persist user corrections in `nl_corrections.db` (SQLite, WAL mode),
+  identical schema shape to Cypher. Lookups happen before any LLM call.
+
+## Forbidden
+- Asking the LLM to emit AQL directly. The LLM's job is SPARQL only;
+  the deterministic transpiler turns SPARQL into AQL.
+- Inlining the entire OWL ontology when a tenant-scoped slice would do
+  — pre-trim the Turtle to the tenant's reachable classes/properties.

arango_sparql_py-0.2.0/.cursor/rules/400-frontend-ui.mdc

@@ -0,0 +1,58 @@
+---
+description: Frontend rules — Vite + React + TS + CodeMirror SPARQL + Cytoscape RDF visualization
+globs:
+  - "ui/**/*.{ts,tsx,css,html}"
+  - "ui/package.json"
+  - "ui/vite.config.ts"
+---
+
+# Frontend rules
+
+## Stack (mirror `arango-cypher-py/ui/`)
+- **Vite + React 19 + TypeScript**, ESM-only.
+- Editor: **CodeMirror 6** with `@codemirror/legacy-modes/mode/sparql`
+  for syntax highlighting. Mirror the structure of
+  `references/arango-cypher-py/ui/src/components/CypherEditor.tsx` in a
+  new `SparqlEditor.tsx`.
+- Graph viz: **Cytoscape.js**, mirror
+  `references/arango-cypher-py/ui/src/components/CytoscapeGraph.tsx`.
+- Tailwind v4 via `@tailwindcss/vite` (same as Cypher UI).
+
+## Component map (1:1 with Cypher UI where it carries over)
+- `SparqlEditor.tsx` ← `CypherEditor.tsx`
+- `AqlEditor.tsx` ← keep as-is, it's language-agnostic.
+- `CytoscapeGraph.tsx` — extended for RDF (see below).
+- `SchemaGraph.tsx` / `CytoscapeSchemaGraph.tsx` — render OWL classes
+  + properties from the ontology endpoint.
+- `MappingPanel.tsx`, `ParameterPanel.tsx`, `ResultsPanel.tsx`,
+  `QueryHistory.tsx`, `SampleQueries.tsx`, `ConnectionDialog.tsx`,
+  `TenantSelector.tsx`, `SchemaWarningBanner.tsx`, `ClauseOutline.tsx`,
+  `theme.ts` — port verbatim with SPARQL-flavored copy.
+
+## RDF graph rendering rule (the key UX delta vs Cypher)
+- In strict RDF every literal is a node. That clutters Cytoscape badly.
+- Default render mode: **collapse RDF literal nodes into properties on
+  their subject node**. Edges to literals become key/value pairs in the
+  subject's tooltip / side panel.
+- Provide a UI toggle ("Show literals as nodes") that opts back into the
+  raw triple view for power users.
+- IRI nodes keep their full IRI as a hover tooltip; the displayed label
+  is the local name (after `#` or last `/`), or `rdfs:label` when present.
+
+## Lang module
+- `ui/src/lang/sparql.ts` — wires the legacy SPARQL mode + a
+  hover/completion provider that pulls term definitions from the
+  ontology endpoint. Mirror `cypher.ts` / `cypher-completion.ts` /
+  `cypher-hover.ts`.
+
+## API client
+- `ui/src/api/` mirrors the Cypher project's API folder: typed wrappers
+  around `/translate`, `/execute`, `/execute-aql`, `/validate`,
+  `/explain`, `/nl/sparql`, `/schema/owl`, `/connect`. Use `fetch` with
+  `credentials: "include"` and pass through the session token header.
+
+## Forbidden
+- `react-router` unless the app actually grows multi-route — the Cypher
+  UI is single-page and so is this one initially.
+- Any Cypher-flavored editor mode in the SPARQL editor; pick `sparql`
+  explicitly, do not auto-detect.

arango_sparql_py-0.2.0/.cursor/rules/checkpoint-regularly.mdc

@@ -0,0 +1,44 @@
+---
+description: Commit early, push often - never lose work to uncommitted changes
+alwaysApply: true
+---
+
+# Checkpoint Regularly
+
+> **"Commit early, push often, never lose work."**
+
+Large, uncommitted changesets are disasters waiting to happen.
+
+## Checkpoint Triggers
+
+You MUST commit and push when:
+
+| Trigger | Why |
+| --- | --- |
+| Feature complete | Logical unit of work done |
+| Tests passing | Known-good state worth preserving |
+| Before risky refactor | Safety net if refactor fails |
+| After ~30 minutes of work | Time-based protection |
+| Before switching tasks | Clean handoff point |
+| Before ending session | Never leave work uncommitted |
+
+## Git Discipline
+
+### Commit Messages
+
+```bash
+# GOOD: Descriptive, scoped
+git commit -m "feat(wormhole): wire initializeCentroids to respect config"
+git commit -m "fix(aboyeur): integrate createWorkItemsFromChecklist"
+
+# BAD: Vague
+git commit -m "updates"
+git commit -m "wip"
+```
+
+### Rules
+- One logical change per commit
+- If you can't describe it in one line, it's too big
+- Push immediately after every commit — push is free, losing work is expensive
+
+**Checkpoint. Push. Repeat.**

arango_sparql_py-0.2.0/.cursor/rules/comprehensiveness-over-simplification.mdc

@@ -0,0 +1,64 @@
+---
+description: Production-ready mandate - never simplify away completeness in error handling, edge cases, security, tests, observability, or config
+alwaysApply: true
+---
+
+# Comprehensiveness Over Simplification
+
+> **"If a feature ships incomplete, it didn't ship—it leaked."**
+
+You are building **production systems**. Simplification is the enemy of completeness.
+
+## Completeness Dimensions
+
+Every piece of work must address ALL of the following. Skipping any is a defect.
+
+### Error Handling
+- No swallowed errors — every `catch`/`if err != nil` must DO something
+- Descriptive messages — WHAT failed, WITH WHAT input, WHY
+- Context wrapping — `fmt.Errorf("loading config: %w", err)`
+- Graceful degradation over crashing
+
+### Edge Cases
+Every function must handle: empty/nil inputs, boundary values, invalid inputs, unicode/special chars, concurrent access.
+
+### Configuration Over Hardcoding
+If a value could EVER differ across dev/staging/prod, it must be configurable.
+
+### Test Completeness
+Cover: happy path, error paths, edge cases, concurrency, regressions.
+
+### Observability
+Structured logging (not `fmt.Println`), metrics, tracing, health checks, alertable events.
+
+### Security
+Input validation at boundaries, no secrets in code/logs, auth/authz checks, least privilege.
+
+### Documentation
+Public function docstrings, README updates, API docs with examples, architecture notes for non-obvious decisions.
+
+### UI/UX (Frontend)
+Handle: loading, error, empty, success states. Accessibility (ARIA, keyboard nav). Responsive design.
+
+### Data Integrity
+Validate at boundaries, database constraints, transaction safety, idempotency.
+
+### Performance
+Pagination, caching, lazy loading, indexing, connection pooling.
+
+## Anti-Patterns (NEVER Do)
+
+| Anti-Pattern | Consequence |
+| --- | --- |
+| Happy Path Only | Production incidents |
+| "We'll Add That Later" | "Later" never comes |
+| Empty Catch Blocks | Hidden failures |
+| Magic Numbers | Unmaintainable code |
+| Copy-Paste Coding | Divergent behavior over time |
+| Console.log Debugging | Noise in production logs |
+
+## The Mantra
+
+> **"Complete is better than clever. Robust is better than fast. Production-ready is the only ready."**
+
+When in doubt, do MORE, not less.

arango_sparql_py-0.2.0/.cursor/rules/incremental-over-atomic.mdc

@@ -0,0 +1,50 @@
+---
+description: Small verifiable steps over big-bang changes - each increment must compile, pass tests, and be functional
+alwaysApply: true
+---
+
+# Incremental Over Atomic
+
+> **"Small steps that individually work > Large steps that eventually work."**
+
+Big-bang changes are high-risk gambles. Incremental changes are safe, reviewable, and reversible.
+
+## Instead of Big Bang → Incremental Slices
+
+| Big Bang | Incremental |
+| --- | --- |
+| Refactor entire module at once | Refactor one function, verify, commit, repeat |
+| Add feature + tests + docs in one PR | Types first → logic → tests → docs |
+| Replace old system with new | Run both in parallel, migrate gradually, remove old |
+
+## Each Increment Must Be
+
+- **Verifiable** — can be tested independently
+- **Reversible** — can be rolled back without affecting other changes
+- **Reviewable** — small enough to understand in < 5 minutes
+- **Deployable** — doesn't break the build in isolation
+
+If an increment takes more than 30 minutes, slice smaller.
+
+## The Working State Rule
+
+At every checkpoint, the codebase MUST: compile, pass tests, be functional.
+
+## Refactoring Pattern
+
+```text
+# GOOD: Incremental
+1. Add new function alongside old → verify (commit)
+2. Migrate one caller → verify (commit)
+3. Repeat until all callers migrated
+4. Remove old function (commit)
+```
+
+## Anti-Pattern Detector
+
+- Changing more than 5 files at once → **Slice smaller**
+- Working 1+ hour without a commit → **Checkpoint now**
+- Unable to describe the change in one sentence → **It's too big**
+- Afraid to run tests because "it's not done yet" → **You've gone too far**
+
+**Small steps. Verify each one. Never break the build.**

arango_sparql_py-0.2.0/.cursor/rules/modularity-and-structure.mdc

@@ -0,0 +1,53 @@
+---
+description: Everything has a place - enforce file size limits, directory conventions, and module cohesion
+alwaysApply: true
+---
+
+# Modularity and Structure
+
+> **"Everything has a place. Put everything in its place."**
+
+## File Size Limits
+
+| File Type | Max Lines | Action If Exceeded |
+| --- | --- | --- |
+| Source code | 1500 | Split into multiple files |
+| Test files | 2000 | Split by test category |
+| Config files | 500 | Use includes/imports |
+| Documentation | 1000 | Split into sections |
+
+### Signs a File Needs Splitting
+- Can't find things without search
+- Multiple unrelated concerns
+- Multiple people need to edit it simultaneously
+
+## File Placement Rules
+
+| File Type | Goes In | NOT In |
+| --- | --- | --- |
+| Shared types | Core/types module | Random location |
+| Tests | Next to source file | Separate `tests/` folder (except E2E) |
+| Configs | `configs/` | Root directory |
+| Scripts | `scripts/` | Root directory |
+
+## Module Cohesion
+
+Each package/module should:
+- Have a single responsibility
+- Expose a minimal public API
+- Hide implementation details
+- Be independently testable
+
+## Before Creating Any File
+
+| Check | Question |
+| --- | --- |
+| Location | Is this the right directory? |
+| Naming | Does the name follow existing conventions? |
+| Size | Will this file stay under limits? |
+| Cohesion | Does this file belong with its neighbors? |
+| Discoverability | Can someone find this file intuitively? |
+
+> A new developer should be able to find any file based solely on what it does, without searching.
+
+**Structure is not bureaucracy—it's navigation.**

arango_sparql_py-0.2.0/.cursor/rules/read-before-write.mdc

@@ -0,0 +1,52 @@
+---
+description: Match the codebase - search for existing patterns, utilities, and conventions before writing new code
+alwaysApply: true
+---
+
+# Read Before Write
+
+> **"Match the codebase, don't fight it."**
+
+Before writing ANY code, understand what already exists. The codebase has patterns, conventions, and utilities. Use them, don't reinvent them.
+
+## The Reading Protocol
+
+Before implementing anything:
+
+1. **Pattern Search** — How does the codebase already do this?
+2. **Utility Search** — Is there a helper for this?
+3. **Existing Implementation** — Has someone already solved this?
+4. **Test Pattern Search** — How are similar things tested?
+
+## What You Must Find Before Writing
+
+| Before Writing | Find First |
+| --- | --- |
+| New struct/type | Existing similar types |
+| New function | Existing utilities with same behavior |
+| New endpoint | Existing endpoint patterns |
+| New test | Existing test helpers/patterns |
+| New error type | Existing error conventions |
+| New config field | Existing config structure |
+
+## Pattern Matching Requirements
+
+When you find existing patterns, you MUST:
+1. Use the same naming conventions
+2. Use the same file organization
+3. Use the same error handling style
+4. Use the same logging approach
+5. Use existing utilities — don't write `formatTime()` if `utils.FormatTime()` exists
+
+## The Duplication Detector
+
+| Question | If Yes → |
+| --- | --- |
+| Does this function already exist? | Use it |
+| Does a similar type already exist? | Extend or reuse it |
+| Is there a util/helper for this? | Call it |
+| Is there an established pattern? | Follow it |
+
+The codebase was here before you. Your job is to make it *more* consistent, not less.
+
+**Read first. Match the patterns. Then write.**

arango_sparql_py-0.2.0/.cursor/rules/surface-dont-guess.mdc

@@ -0,0 +1,56 @@
+---
+description: When unsure, ask the user - never silently guess on ambiguous requirements, architecture, or scope
+alwaysApply: true
+---
+
+# Surface Don't Guess
+
+> **"When unsure, ask—don't bet the codebase."**
+
+A wrong guess implemented is worse than an honest question asked.
+
+## When You MUST Ask
+
+| Situation | Why |
+| --- | --- |
+| Ambiguous requirements | "Add caching" — Cache what? Where? How long? |
+| Multiple valid approaches | Sync or async? REST or gRPC? |
+| Breaking changes | Will this affect existing callers? |
+| Architectural decisions | New service or extend existing? |
+| Unclear scope | Is this feature supposed to include X? |
+| Missing context | Why does this code exist? |
+
+## The Uncertainty Protocol
+
+1. **Attempt Self-Resolution (60 seconds max)** — Search codebase, check docs, look at tests
+2. **If Still Uncertain → ASK** — State what you understand, what's unclear, and options with tradeoffs
+3. **WAIT** — Do NOT proceed with a guess
+
+## Good vs. Bad
+
+```text
+# BAD: Silent Guessing
+User: "Add retry logic"
+Agent: *implements exponential backoff with 5 retries, 1s delay, max 30s*
+User: "Why 30 seconds? I wanted 3 quick retries."
+
+# GOOD: Surfacing Uncertainty
+User: "Add retry logic"
+Agent: "Before I implement:
+1. Max retries: 3? 5?
+2. Backoff: fixed? exponential? jitter?
+3. Which errors trigger retry?
+4. Max total timeout?"
+```
+
+## Cost of Guessing
+
+| Guess | Cost |
+| --- | --- |
+| Wrong architecture | Days of refactoring |
+| Wrong behavior | User-facing bugs |
+| Wrong scope | Wasted effort |
+
+**Cost of asking: 30 seconds of the user's time.**
+
+Your confidence is not a substitute for their knowledge. **Ask.**