How the Rules system works

1. What this system is — and what it is not

VPAA Rules is a structured layer above the full text of Serbian building and planning regulations and selected planning documents. Instead of asking a person or an AI model to read thousands of articles from scratch for every question, the database extracts requirements that can actually be checked on a project: measurable limits, clear obligations, applicability conditions, traps and exact source quotations.

A rule is useful only when it remains traceable to its source. For that reason a usable record contains the regulation or plan, official gazette, article, literal quotation, a human-readable question and answer, and—where possible—a structured machine check.

2. Three ways to use the system

Parcel / Plan Context

Plan Context is the planning layer in front of the general Rules engine. Open /provjeri-parcelu/ and identify a Belgrade location either by cadastral municipality + parcel number or by a WGS84 point / map click. The service queries public Beoland GIS layers, then tries to connect the returned zone to a locally verified planning record with an official-gazette reference and literal quotation.

The result deliberately separates informational GIS context from verified planning parameters. A GIS number is useful for discovery, but it is not promoted to a legal planning threshold unless the response says can_conclude_legal_parameters=true.

Hierarchy and ambiguous boundaries

Indicative development potential

When parcel area and usable coverage/FAR values are available, the page may show quick footprint and gross-floor-area arithmetic. GIS-only inputs are marked indicative_from_gis and can_use_as_legal_parameter=false. Setbacks, height, green area, parking, access, heritage, infrastructure and other constraints may reduce achievable GFA.

REST API

POST /api/v2/rules/plan-context/
Content-Type: application/json

{"parcel":{"cadastral_municipality":"Zemun","number":"1234/5"}}
// or: {"lat":44.8125,"lon":20.4612}

Read coverage, resolution.status, resolution.hierarchy, can_conclude_legal_parameters, plan, zone, parameters.verified, parameters.informational_gis, development_potential, risks, sources and warnings.

MCP · get_plan_context

An MCP agent should call get_plan_context before parcel-specific Belgrade planning answers when the parcel or coordinate is known. It must not convert GIS-only values into legal facts from model memory. Ambiguous boundaries or a controlling PDR/specific plan require explanation/manual verification instead of falling back to PGR.

3. How the public search works

The search box is intentionally not a general-purpose chatbot. It searches the structured rule corpus. Serbian Latin, Serbian Cyrillic and diacritics are normalized so the same concept can match across scripts. Common question/helper words and very short words are removed, while longer words are reduced to rough stems so case endings do not unnecessarily kill a match.

The remaining word roots are combined conservatively: all of them should match somewhere in a rule. If that gives zero results, the engine gradually removes the rarest blocking term until it finds the broadest useful core. It deliberately does not switch to a huge “match any word” result set, because a noisy list is dangerous in a regulatory context.

Filters

• Area / oblast: narrows the subject area.
• blokira / proveriti / informativno: severity/use category.
• potvrđeno / izvedeno: verification status. Revision rules are hidden from public visitors.

4. How to ask the best question

For an AI agent, natural language is welcome—but the facts must be explicit. A strong question tells the agent what the project is, where it is, what condition is being checked, and the actual measured value with its unit. Do not force the client to know database field names; the agent should map ordinary language to the current schema exposed by the server.

A useful question template

Project: [house / apartment building / hotel / commercial / mixed use]
Location: [city + plan/zone if known]
Stage: [before location conditions / PGD / works / technical inspection]
Relevant facts: [garage, number of dwellings, building position, protected area...]
Measurement: [value + unit]
Question: [one concrete regulatory check]
Then: tell me what information is missing and cite every rule you rely on.

Compound questions are allowed, but a good AI agent should decompose them into separate canonical checks instead of sending one vague mega-query.

5. How to read a rule card

6. Coverage: what is in the database and what is planned

The rule database is intentionally transparent about incompleteness. A regulation can be in the full-text corpus and registry before any structured rule has been extracted from it. Not every article becomes a rule: definitions, transitional provisions and purely procedural text may be read and deliberately skipped, while measurable requirements and clear project obligations are extracted with a literal quote.

Planning documents are tracked separately from national regulations. They matter because a specific plan can override a general rule for a location; therefore plan-specific rules must never be applied without the relevant location/zone context.

Sources already producing structured rules

Registry backlog — present in the corpus, not yet converted into rules

This live list is the clearest current roadmap of regulations waiting for structured extraction. It changes automatically as sources are processed.

• Zakon o državnom premeru i katastru (159 articles)
• Zakon o ozakonjenju objekata (47 articles)

7. The core AI principle: language model for language, rule engine for facts

Applicability is three-state: true, false or unknown. Unknown is not “probably yes”; it means the agent lacks a project fact required to decide whether the rule applies.

8. REST API

The discovery endpoint is the starting point for every robust client. Do not hard-code the profile fields or measurement metric names in an AI application: read the schema exposed by the deployed corpus.

Discovery

curl -sS https://vladimirperovic.com/api/v2/rules/

Focused rule search

curl -sS https://vladimirperovic.com/api/v2/rules/query/ \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "Kolika je svetla visina garaže?",
    "concepts": ["garage_clear_height"],
    "profile": {"grad": "Beograd"}
  }'

Concrete measurement check

curl -sS https://vladimirperovic.com/api/v2/rules/check/ \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "Da li mi je garažna rampa dovoljno široka?",
    "checks": ["garage_ramp_width"],
    "profile": {"garaza_u_objektu": true},
    "measurements": {
      "cista_sirina_rampe": {"value": 270, "unit": "cm"}
    }
  }'

The metric name above is an example from the current corpus. Production clients should discover the live measurement schema rather than assuming that field name forever.

Broad audit

curl -sS https://vladimirperovic.com/api/v2/rules/audit/ \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": {
      "grad": "Beograd",
      "namena": "stanovanje"
    },
    "measurements": {}
  }'

Request rules

• POST endpoints require Content-Type: application/json.
• JSON body limit is 128 KiB.
• Unknown profile keys and measurement metrics are rejected rather than silently ignored.
• Numeric measurements require both value and unit.
• Compatible units are normalized deterministically before comparison.
• If VPAA_RULES_API_KEY is configured on the server, add Authorization: Bearer .

9. MCP: connecting Claude or another AI agent

The remote MCP endpoint is:

https://vladimirperovic.com/mcp/

The server exposes three main tools:

• search_rules — find verified rules relevant to a focused question.
• check_project — evaluate selected checks against explicit project facts and measurements.
• audit_project — run a broader pre-submission scan across current verified coverage.

Generic setup

1. In your MCP-capable client, add a remote HTTP MCP server pointing to the URL above.
2. If the server is in private API-key mode, configure the Bearer Authorization header if the client supports custom headers.
3. Verify that the client can list the tools. The agent should inspect the current tool schema rather than assume old field names.
4. Give the agent the behavioral instructions in the next section.

Illustrative client concept (exact configuration keys depend on the MCP client):

name: vpaa-rules
transport: remote HTTP
url: https://vladimirperovic.com/mcp/

10. Recommended instructions for an AI agent

This is the important part. Connecting the MCP server is not enough; the agent must know how to behave when regulatory information is incomplete.

You are using VPAA Rules as the source of regulatory facts for Serbian building/project questions.

1. Never provide a legal/regulatory threshold from model memory.
2. Read the currently exposed VPAA tool/schema before mapping fields.
3. Decompose compound client questions into focused checks.
4. Extract only facts the client explicitly stated or that are reliably available from project data.
5. Never invent a profile fact just to make a rule applicable.
6. Preserve every measurement with its explicit unit. If the unit is unknown, ask for it.
7. Use search_rules to retrieve relevant verified rules, check_project for concrete checks, and audit_project for broader pre-submission review.
8. Treat applicability=unknown as missing information, not as true.
9. Explain only verified findings returned by VPAA Rules. Cite the regulation, article and source supplied by the tool.
10. If missing_information is returned, ask the client for those facts before making the affected conclusion.
11. If coverage says unverified_match_only or no_verified_answer, state clearly that the verified database is not sufficient for that conclusion.
12. Never convert no_detected_issue into “the project is approved/compliant”. It only means no issue was detected within the verified checks that could actually be evaluated.
13. If a relevant local plan/location condition may override a general rule and the location context is missing, ask for the plan/zone/location conditions.
14. Keep the client-facing answer in normal language. Do not dump raw JSON unless requested.

11. How to interpret AI results

12. Common errors and troubleshooting

13. Security, data integrity and limitations

• The website opens the rules database read-only. Production web requests do not write regulatory data into SQLite.
• Rules marked for revision are excluded from the public AI engine. They cannot be re-enabled by an agent parameter.
• AI conclusions are verified-only by design.
• Every usable rule remains traceable to regulation/plan, gazette, article and literal quote.
• Unknown applicability stays unknown. Missing units or incompatible units fail closed.
• REST and MCP are rate-limited; REST can optionally be protected by VPAA_RULES_API_KEY.
• MCP validates Origin and supports an explicit allow-list for browser origins.

14. Complete example: client → AI → VPAA Rules → answer

Client: “I have a house with an underground garage in Belgrade. The ramp is 270 cm wide. Is that enough and what else should I check before submission?”

1. The agent identifies a garage-ramp-width check and a broader pre-submission intent.
2. It records only stated facts: Belgrade, house, underground garage, 270 cm ramp. It does not invent zone, number of vehicles or fire strategy.
3. It reads the live tool/schema and maps 270 cm to the current canonical measurement metric.
4. It calls check_project for the specific check.
5. It explains only verified applicable findings, using the source returned by the tool.
6. If the engine returns missing information, the agent asks for it.
7. If the client also wants “everything before submission”, the agent can then call audit_project, while clearly limiting the result to current verified coverage.