Welcome to GenAI-Logic

Governed Executable Requirements

Describe it, and get a real system:

For today: a working API, Admin App, and governed logic, built from a prompt

Leverage AI for what it's great at — database design, data mapping, and more. Start from a prompt alone and AI designs the database too, or point it at your existing database and skip straight to the logic. Either way, your AI assistant reads whatever you already have — plain English, Gherkin, pseudocode — and hands business logic off as rules, not code.

 

And it fits: uses your existing org, technology, and practices

What comes out the other end is exactly what you already run:

1. A business user can drive it, in the requirements format they already write — plain English, Gherkin, pseudocode, even actual regulation text; no database design, screen painting, or scripting to learn.
2. Standard IDE, standard language — a project in the IDE and language you already use, ready to extend.
3. Standard deploy — a standard container; cloud or on-prem, no additional charges.
4. Standard enterprise infrastructure — pluggable security (SQL or Keycloak), full REST API, event/messaging integration (Kafka, webhooks) — built in, not bolted on, same as any other enterprise system.

 

And for tomorrow: systems governed by rules you can Read, Trust, and Maintain

The key idea: that split — AI for executable intent, declarative rules for governance — is the whole point. Here's what "governed" means in practice:

• Read — 5 rules, not ~200 lines of code. A rule you can point to and know what it does, at a glance.
• Trust — those rules run at one commit point, no matter which path the transaction came in on — API, MCP, agent, Kafka. No bypass.
• Maintain — add a rule anywhere, and the engine resolves dependency order automatically. No untangling existing code to find where it belongs.

And you're not alone throughout: ask your AI assistant anything — architecture, rules, debugging, deployment, or how the system works.

This is the start page for the GenAI-Logic Manager — where you manage projects, create notes and resources, etc.

 

🤖 AI Assistance

We get good results with Claude Sonnet 5. In this environment, GitHub Copilot is what's available — pick Sonnet 5 if you can. Then say:

Please load `.github/.copilot-instructions.md`.

Detailed steps, what to expect, model/cost info, and why we recommend a frontier model

 

See "Quota reached" in the status bar? Safe to ignore — it doesn't mean anything is broken or unavailable.

This takes 20-30 seconds. You'll see "Working" the whole time with no other feedback — that's normal, not stuck.

 

Step by step:

1. Open the Chat tab in the right-hand panel.
2. Click the model pill at the bottom of the chat box (shows Auto by default).
3. If Claude Sonnet 5 appears in the list: select it. If it's not there: click Other Models near the bottom of that same list — this expands the list to show more models, including Claude Sonnet 5. Still not there (Free/Student plans — see below): leave it on Auto.
4. Type the command above and press Enter.

 

  Which model, and what does this cost?

Model selection is plan-dependent (GitHub changed this June 2026):

• Copilot Free / Student: Chat and Agent mode only run in Auto — GitHub picks the model for you from a pool that includes Claude Sonnet 4.6 among others. You cannot force Claude specifically.
• Copilot Pro ($10/mo) and above: Manual model selection is available — but Claude Sonnet 5 may not appear until you click Other Models to expand the list (see step 3 above).

Cost, in practice: All plans (including Free) include a monthly allotment of GitHub AI Credits for chat/agent usage — the Free plan's is small but real; Pro includes about $15/month worth. Two things keep a GenAI-Logic project cheap relative to that allotment:

• The scaffold — the API, Admin App, and database models — is generated by template, not by AI. The AI is only doing the design/logic work (schema decisions, rule translation, Q&A) — a small fraction of what you actually get.
• If you exceed your monthly credits, GitHub does not silently charge you — on individual plans you're prompted to either wait for the next cycle or opt in to paid overage; it does not happen by accident.

For current figures, see GitHub Copilot plans & pricing.

 

  Why we recommend a frontier model

The mechanical parts of this system — folder structure, rule syntax, provenance files — come through reliably even on lighter/auto-selected models. What separates frontier models (Claude Sonnet 4.6/5, GPT-5, etc.) is judgment on subtler cases: patterns documented in the training material that require reasoning about why a naive implementation is wrong, not just matching a syntax example. In testing, a smaller auto-selected model built a project correctly, then wrote a real correctness bug into a follow-up rule that our own docs specifically call out as an easy mistake — and reported it as verified when it wasn't.

For exploring the product, any available model is fine. For real logic you intend to keep, pick a frontier model explicitly when your plan allows it — and review the AI's output either way, the same as you would any other engineer's.

For more information, see AI-Enabled Projects or click here.

 

🚀 First Time Here?

 

You're already running in GitHub Codespaces — a cloud VS Code environment in your browser. Nothing to install. (Use Chrome or Edge — Safari has known compatibility issues with VS Code in the browser.)

The Ideal — executable business prompts, held to an enterprise standard

Heads up: you're about to switch to the AI chat panel, and back. The browser tab showing this README forgets which sections below are open/closed when you return — so open the README on GitHub (ApiLogicServer/codespaces_mgr) in a split-view tab first (once), and it won't happen again.

  Show me how

Right-click the GitHub README tab and choose New Split View with Current Tab:

You'll end up with the Codespace on one side and the README on the other — switch between AI chat and README without losing your place:

Say this to your AI assistant (allow several minutes):

Create basic_demo from samples/dbs/basic_demo.sqlite.

On Placing Orders, Check Credit:    
    1. The Customer's balance is less than the credit limit
    2. The Customer's balance is the sum of the Order amount_total where date_shipped is null
    3. The Order's amount_total is the sum of the Item amount
    4. The Item amount is the quantity * unit_price
    5. The Item unit_price is copied from the Product unit_price

Use case: App Integration
    1. Publish the Order to Kafka topic 'order_shipping' when the date_shipped is not None.

Starting from a new database instead?

 

The prompt above starts from an existing database — the common real-world case, and much faster (no schema design step). You could have AI design a new database from scratch instead:

Say this to your AI assistant (allow several minutes):

Create basic_demo from samples/prompts/genai_demo.prompt

 

During project creation, a browser tab may auto-open (or offer to) showing it running — safe to decline or dismiss.

The goal here isn't a demo — it's an enterprise-class system you can trust and maintain. That's exactly what gets tested next.

 

AI is great — but logic-as-code is hard to Read, Trust, and Maintain — here's why

AI is genuinely good at UI, data mapping, boilerplate, etc — no argument there. Business logic is the exception.

On a real system, business logic routinely consumes half the development and debugging effort — and it's the half that determines whether the system is actually correct.

Left unguided, any AI assistant — including the one that just built basic_demo for you — would default to procedural code for logic like this. Ask it directly, and you get three problems:

• Not readable. procedural/credit_service.py — ~200 lines for those same 5 requirements. Open it and judge for yourself. Now picture a real system: 10-20X the requirements of this example, and proportionally more procedural code to match. Nobody can audit that at a glance — not the next developer, not compliance, not you in six months. At that scale, an auditor can't read it all — they can only sample, and hope. Unreadable at scale is ungovernable at scale.

• Not trustworthy. The procedural version shipped 2 real bugs — found only by specifically testing what happens when a row is reparented to a new owner: the A/B test. Root cause: path confusion — procedural code must enumerate every change path (insert, update, delete, reparent) by hand, and it's easy to miss one.

• Not maintainable. Two options:

  • Alter the generated code: that means re-checking every execution path and getting the order right, by hand, again. Root causes: path confusion and manual ordering — the same problem as above, back for round two. Honestly? At some point you'd stop checking and just hope testing catches it.

  • Change the prompt and regenerate: doesn't dodge the risk, it repeats it — the AI is re-deriving all ~200 lines from scratch, with no guarantee it reproduces the paths that already worked. Same odds of a new bug, same review effort, again — and it only gets more expensive as the system grows.

There's a structural problem underneath the bugs, too: AI pattern-matches dependencies, it doesn't compute them — so the odds of a miss go up as the system grows, no matter how capable the model. More detail →

That's not a capability gap — it's a representation problem, and no amount of AI capability fixes that.

We're deeply impressed with AI — this is about closing the one gap it has: logic. That's next.

 

AI-driven rules are easy to Read, Trust, and Maintain — here's how

 

  1. Run it — see the API and logic operate

You've probably used AI to generate code before — so what's different here?

Difference 1: it produces models, not code. Run the basic_demo prompt above, and instead of a pile of procedural code, you get artifacts that declare structure or policy rather than procedure — same 5 requirements, same AI:

1. Data model — database/models.py
2. Full JSON:API — Swagger, pagination, optimistic locking (api/expose_api_models.py — 52 lines, zero per-table code)
3. Admin App — multi-table, with navigations and lookups (ui/admin/admin.yaml — simple YAML, not HTML/JS)
4. Business logic — logic_discovery/place_order/check_credit.py — 5 rules (~40X less), same requirements, same AI, 0 bugs

Difference 2: the logic itself is declarative. 5 lines, intent still clear — not ~200 lines of procedural frankencode. That's what declarative buys — more on that below.

Each small, readable, yours. Plain Python — standard tooling applies. Security is opt-in, not default — bootstrap RBAC anytime with genai-logic add-auth.

See it running: Press F5 using "API Logic Server Run (run project from manager)", and open the Admin App. Explore the API via Swagger, browse the data, and follow the relationships — all auto-generated from the data model.

Now trigger it: open an unshipped Order for Alice, edit the Widget item:

Change the quantity to a very large number. Save.

  Detail Instructions -- Screen Shots

Alter the quantity for an unshipped item:

1. Show the Customer List
2. Show the first Customer
3. Show first Order
4. Edit the Item
5. Set the quantity

The save fails — note the dialog. Why? Let's look.

 

  2. Debug it — standard logging, standard debugger

No new tools required. The rule chain that just fired is in the log — plain text, readable in your terminal or editor: sample trace. A live run writes the same thing to the standard log, logs/als.log.

Every rule is a plain Python function or lambda. Set a breakpoint on any calling= function or as_condition= lambda in your IDE, exactly like you would anywhere else in the codebase — no proprietary debugger, no special UI.

 

  3. Iterate — 1 AI prompt adds table, relationship, 2 rules

Ask your AI assistant for a new rule, in plain English:

Customers should not be able to create new orders if they have unresolved past due letters.

There was no Letter table in the model — the AI adds it, relates it to Customer, and declares a count + a constraint. One sentence creates a schema change and two new rules — automatically integrated with the 5 already there. No need to open check_credit.py to find where this belongs, or trace the other rules to check for conflicts.

A lot just happened here — worth a closer look.

 

  4. Why Rules Are Declarative — automatic calling, automatic ordering

This iteration — like maintenance generally — was remarkably simple, because rules are declarative:

• No need to call the new logic. Rules are invoked automatically - regardless of the originating path. You can trust that they'll always run.
• Order doesn't matter. Open check_credit.py and shuffle the five rules into any order you like. Rerun — still correct. Try that with 200 lines of procedural code. You can trust that they'll run in the right order.
• You got more than you asked for. The original requirement said "On Placing Orders, Check Credit" — insert time. But the save that failed was an edit to an existing order. Nobody wrote an update-time check.

Functions don't behave like that. So why is that?

Traditional logic is procedural — you own how: when it's called, and in what order. Declarative logic — rules — is about what, not how: you state the fact, and the system takes responsibility for invocation and ordering. That's why the new rule didn't need to be called, and why order didn't matter.

The next section explores this in detail. Ask your AI assistant — "What are rules?" — or keep reading.

 

  5. How Declarative Rules Make Logic Easy to Read, Trust, and Maintain

Rules enforce business policy — multi-table derivations, constraints, and actions like messaging. LogicBank, the rule engine, hooks SQLAlchemy's commit event to run them on every transaction — authored as plain Python functions in logic/logic_discovery/, readable, version-controlled, owned like any other source file.

How it works:

1. At startup — rules load, and the engine computes their dependency graph once.
2. At commit — for each transaction, the engine finds the rules relevant to what changed, and fires them in the right order.

Unlike procedural code, they're declarative — solving exactly the three problems raised above (AI great, but hard to Read, Trust, and Maintain):

Property	What it means	Why it matters
Readable	5 lines, one per requirement — declared once, e.g. Customer.balance = sum of unpaid orders	No archaeology needed to see what it does
Trustworthy	Rules fire at every commit, from every caller, on every insert and edit — you never call them	Can't be forgotten, can't be bypassed
Maintainable	Dependency order is computed once, automatically — not written into your source file	Add a rule anywhere, it finds its place

Think of a spreadsheet: B10 = SUM(B1:B9) isn't called, it reacts — change any input cell, it recalculates. Rules react the same way to changes in what they depend on.

Procedural code is hard to read — so you can't tell whether it's called from every caller, in the right order. That's not a testing gap; it's a representation problem.

Declarative rules are easy to read — the intent, now rigorous — and with no bypass and automatic ordering.

You can read the rules, and trust they are being enforced. Always.

How this works: Context Engineering (CE) + a commit-time rules engine

Two things have to be true for this to work:

Step 1 — Context Engineering trains the AI to write rules, not code. That same AI, left unguided, would have produced the ~200 buggy lines from earlier. Writing rules instead wasn't its own idea — it was told to, in detail, by Context Engineering — the same files driving this conversation right now:

• Directs rules, not code. When you ask for business logic, CE steers the AI toward the right rule type (sum vs. count vs. Allocate vs. Request Pattern) for what you actually asked for, instead of letting it default to the procedural code it's seen a million times in training.

  • Rules become the default, easy path — not a discipline a team has to maintain by hand: familiar requirements in, rules — Read, Trust, Maintain — out.

• Trains the AI to automate everything above, and to help you when it breaks. EAI's 2-message Kafka pattern, the AI/Request Pattern wiring, Executable Requirements' pre-coding schema assessment — all of it is documented training material (docs/training/*) the AI reads before writing your code, not generic knowledge it's guessing from. Ask "what are rules?" or "how do rules work?" — or, without an AI handy, just read samples/basic_demo_logic_gov/logic/readme_logic.md — same material.

• Answers your own questions, too. Same materials, same AI — ask it directly:

  • Is this really infrastructure, like a database?
  • Is this a black box? How do I debug a rule chain?
  • Can I verify this with tests, not just take it on faith?
  • What did the AI decide on its own that I should double-check? (the ad-libs report)
  • Can I see a governance/health report for this project's logic?
  • What does it take to migrate off this if we ever wanted to?
  • How does this perform at scale?
  • What does this integrate with — APIs, workflows, agents, MCP?
  • Does this work with my existing database?

  More background: Eval Guide.

  The AI was trained on this material — can you trust its answers?

  
  Don't take them on faith. Ask the same question a different way, or ask something not covered here — like where this architecture breaks down. If it just recites the same lines back, you've caught it. If it reasons, that's the test passing.

Put together: once the AI knows how the system works, it doesn't just generate rules instead of code — it helps you debug them, and helps you understand them. A design assistant, not just a coding assistant.

Step 2 — the rules engine runs the rules. Rules aren't called from your code — they're wired into a single SQLAlchemy before_flush listener, loaded once at server start as described above. Every write, from any path — API, custom endpoint, Kafka consumer, agent — passes through that one listener before it commits. No bypass — there's no second door.

Full writeup: declarative/procedural comparison.

 

Scaling to the Enterprise — here's how

With logic off its plate, AI can create remarkable results — solid enterprise systems, from requirements, not just demos that become tech debt.

We add key enterprise architecture integration:

• Enterprise Integration (EAI) — the demo above showed Publish the Order to Kafka topic. For the subscribe side, see samples/basic_demo_eai/readme.md: B2B orders from partner systems, via a Custom API or Kafka subscriber, including lookups so partners send "Account": "Alice" (not internal IDs).

• MCP — your API is MCP-discoverable out of the box (/.well-known/mcp.json). Copilot, Claude, or ChatGPT can find the schema and answer natural-language queries against it. There's no discovery layer for you to write — see samples/basic_demo_ai_rules-supplier/readme_ai_mcp.md

• AI Rules — rules that call AI for genuinely judgment-call decisions (e.g. picking a supplier under disrupted shipping lanes). Such AI "proposals" are governed by the deterministic rules to ensure results conform to business policy — see samples/basic_demo_ai_rules-supplier/readme.md

• Custom UIs, safely — Vibe tools (Cursor, v0, etc.) generate the UI; it's built against the same governed API, so the logic runs the same regardless of what's calling it — genai-logic genai-add-app --vibe.

• Governance you can prove, not just assert — three reports, generated from the running system, not hand-written:

  • Logic flow diagram — NL requirement, dependency diagram, and rule summary, for every rule chain
  • Ad-libs report — every assumption the AI made beyond the spec, so you know exactly what to verify
  • Health check — rule adoption, dependency-tracking integrity, missing docstrings, across the whole project

  A compliance reviewer can check the implementation in minutes, not by reading code.

  

That combination — AI, logic automation, and that enterprise architecture — is what enables Executable Requirements: AI building real enterprise-class systems, from formats you already are familiar with, not a new syntax to learn:

• Gherkin-style scenarios — business description, and the actual requirements used by AI to create the system.

• The short prompt that built a system straight from an actual government tariff regulation (Canada, CBSA) — the prompt, and the rules it produced

  So, simply by referencing the regs, you get a complete enterprise system — including governed logic you can audit, trust, and maintain. AI implements the spec end-to-end and reports an ad-libs list — every decision it made beyond what the spec said — so you know exactly where it guessed.

 

The architecture that makes this work: two funnels, converging on one engine. All requirement formats, and all transaction sources, passing through the same commit point. No bypass.

What AI delivers, once logic is off its plate: entire, governed systems from requirements — not just code that becomes instant tech debt. It is this approach that caught an 8-figure compliance exposure a major logistics company's hand-coded system missed for months. Full writeup →

 

Go deeper — 30-45 min guided tour

 

Create basic_demo (auto-opens with guided tour option):

genai-logic create --project_name=basic_demo --db_url=sqlite:///samples/dbs/basic_demo.sqlite

Inside the project: Say to your AI assistant: "Guide me through basic_demo" (30-45 min hands-on tour).

Teaches API creation, declarative rules, security, and Python customization. Fail-safe — scripts ensure no coding errors.

 

 

📚 Build It Yourself — Demo Catalog

The section above showed you pre-built samples to browse. These are the same use cases, but as commands you run yourself — paste one into your AI assistant and it builds that project for you, live.

Tip: every project is AI-enabled — once it's built, ask your AI assistant how it works

 

1. Strategic Use Cases (From genai-logic.com)

Explore the key use cases from our home page:

Use Case	Say to your AI / Run	What You'll Learn
Allocation with AI Rules demo_allo_dept_gl	create demo_allo_dept_gl from samples/prompts/allocation.prompt.md or genai-logic create --project_name=demo_allo_dept_gl --db_url=sqlite:///samples/dbs/starter.sqlite	- Cascade Allocation (Costs to Depts/GL) - AI Rules for fuzzy match to project
Use Case 1: AI Rules demo_ai_rules_supplier	genai-logic create --project_name=demo_ai_rules_supplier --db_url=sqlite:///samples/dbs/basic_demo.sqlite	- Use AI Rules (req pattern) to choose Optimal Supplier, per world conditions
Use Case 2: Governed MCP Server demo_mcp_send_email	genai-logic create --project_name=demo_mcp_send_email --db_url=sqlite:///samples/dbs/basic_demo.sqlite	- Bus Users compose new service to send email to overdue customers, subject to email opt-out rules - Create custom API with NL - Create an email service (req pattern)
EAI: Enterprise App Integration demo_eai	genai-logic create --project_name=demo_eai --db_url=sqlite:///samples/dbs/basic_demo.sqlite	- Executable Requirements - Create custom API with NL - Create Kafka Listener with NL
Use Case 4: Vibe Dev Backend demo_vibe	genai-logic create --project_name=demo_vibe --db_url=sqlite:///samples/dbs/basic_demo.sqlite	- UI elements, eg, Cards, Maps, Trees...
Use Case 5: Business Users webgenai	See webgenai/ in this Manager	- Create systems from browser, with logic, sample data and derived attributes
Customs CLVS demo_customs_clvs	genai-logic create --project_name=demo_customs_clvs --db_url=sqlite:///samples/requirements/customs_demo_clvs/database/customs.sqlite	- Governed Business Systems - EAI (using XML), textual requirements
Customs Surtax demo_customs_surtax	implement project demo_customs_surtax from samples/prompts/customs_cbsa.prompt.md	- New Business System from Regulations

 

Running a cloned project? F5 won't work until the venv is set up — see Project-Env for options (genai-logic run, symlink, or local venv).

 

2. Additional Demos

Advanced examples and specialized patterns:

Demo	Say to your AI / Run	What You'll Learn
Executable Requirements	See samples/requirements/readme_reqmts.md	Create from Gherkin requirements implement reqs
New system from prompt	genai-logic genai --using=samples/prompts/genai_demo.prompt	Create systems from prompt Like WebGenAI, but from IDE
Coding Samples	code samples/nw_sample	Useful code examples Search: #als
MCP Discovery demo_copilot_mcp_discovery	genai-logic create --project_name=demo_copilot_mcp_discovery --db_url=sqlite:///samples/dbs/basic_demo.sqlite	test rules via Copilot access to MCP Server

Copy Snippets for venv:

source venv/bin/activate       # windows: venv\Scripts\activate
source ../venv/bin/activate    # windows: ../venv\Scripts\activate
python -m venv venv            # may require python3 -m venv venv

 

Procedures

Detail Procedures

Specific procedures for running the demo are here, so they do not interrupt the conceptual discussion above.

You can use either VSCode or Pycharm.

1. Establish your Virtual Environment

Python employs a virtual environment for project-specific dependencies.

If the project was created in this Manager (or opened from it), the venv is already configured — just press F5.

If the project was cloned from git, choose one of:

• Quickest (no VS Code setup): from the Manager terminal (or, use Code Assistant):

  genai-logic run --project-name=<project-name>

• Mac/Linux with F5: create a symlink to the Manager venv:

  cd <project>
  sh venv_setup/venv.sh symlink
  # reload VS Code window, then F5

• Any platform: create a local venv:

  sh venv_setup/venv.sh go        # mac/linux
  .\venv_setup\venv.ps1 go        # windows

For PyCharm, you will get a dialog requesting to create the venv; say yes.

See Project-Env for more information.

 

2. Start and Stop the Server

Both IDEs provide Run Configurations to start programs. These are pre-built by ApiLogicServer create.

For VSCode, start the Server with F5, Stop with Shift-F5 or the red stop button.

For PyCharm, start the server with CTL-D, Stop with red stop button.

 

3. Entering a new Order

To enter a new Order:

1. Click Customer 1

2. Click + ADD NEW ORDER

3. Set Notes to "hurry", and press SAVE AND SHOW

4. Click + ADD NEW ITEM

5. Enter Quantity 1, lookup "Product 1", and click SAVE AND ADD ANOTHER

6. Enter Quantity 2000, lookup "Product 2", and click SAVE

7. Observe the constraint error, triggered by rollups from the Item to the Order and Customer

8. Correct the quantity to 2, and click Save

4. Update the Order

To explore our new logic for green products:

1. Access the previous order, and ADD NEW ITEM

2. Enter quantity 11, lookup product Green, and click Save.

 

Pre-created Samples

Explore Pre-created Samples

The samples folder has pre-created important projects you will want to review at some point (Important: look for readme files):

• nw_sample_nocust - northwind (customers, orders...) database

  • This reflects the results you can expect with your own databases

• nw_sample - same database, but with with customizations added. It's a great resource for exploring how to customize your projects.

  • Hint: use your IDE to search for #als

• tutorial - short (~30 min) walk-through of using API Logic Server using the northwind (customers, orders...) database

You can always re-create the samples

Re-create them as follows:

1. Open a terminal window (Terminal > New Terminal), and paste the following CLI command:

ApiLogicServer create --project-name=samples/tutorial --db-url=
ApiLogicServer create --project-name=samples/nw_sample --db-url=nw+
ApiLogicServer create --project-name=samples/nw_sample_nocust --db-url=nw

 

Hiding Front Matter

Hiding Front Matter

To hide the YAML or JSON front matter (the metadata block at the top of your markdown files) in the built-in VS Code markdown preview, you can adjust your editor settings:

1. Open the Settings panel using Ctrl + , (Windows/Linux) or Cmd + , (macOS).
2. Search for the following term: markdown.previewFrontMatter.
3. Change the dropdown value from show to hide.

The preview will now automatically strip the front matter from the rendered view.