AabSemantics 2.2.0

AabSemantics: Project Overview and AI Agent Guide

This document provides a high-level description of the AabSemantics repository and precise guidance for AI agents contributing changes. Keep this document concise, actionable, and up to date.

What this repository contains

• Solution: Code/AabSemantics.sln

  • Central solution aggregating core library, modules, extensions, clients, samples, and tests.

• Core: Code/Core/AabSemantics

  • The main semantics engine: concepts, contexts, modules, statements, questions, answers, text, serialization, and utilities.
  • Published to NuGet as the AabSemantics package; it is currently the only packable project in the solution.
  • Subfolders of note:
    • Interfaces/: Public contracts; treat as API surface.
    • Modules/: Built-in Boolean and Classification modules and composition points.
    • Serialization/: Xml and Json DTOs and persistence wire formats; backwards compatibility matters.
    • Text/, Localization/: Text generation, localization, and structured text.
    • Mutations/, Questions/, Statements/: Inference, question processing, and consistency checking.

• Core: Code/Core/Inventor.Algorithms

  • Standalone graph and coding algorithms (Dijkstra, Ford-Fulkerson, Huffman) used independently of the semantics engine.

• Modules: Code/Modules/*

  • Optional domain modules that extend the core engine: AabSemantics.Modules.Set, AabSemantics.Modules.Processes, AabSemantics.Modules.Mathematics.
  • Each module has a matching test project under Code/Tests/AabSemantics.Modules.<Name>.Tests.

• Extensions: Code/Extensions/*

  • EF integration (AabSemantics.Extensions.EF) and WPF integration helpers (AabSemantics.Extensions.WPF).

• Clients: Code/Clients/*

  • AabSemantics.SimpleRestClient: Minimal ASP.NET-based REST service exposing semantics operations.
  • AabSemantics.SimpleWpfClient: WPF showcase UI.

• Samples: Code/Samples/*

  • Small console samples named AabSemantics.Sample01..09, demonstrating statements, questions, modules, customizations, productions, and EF usage.

• Tests: Code/Tests/*

  • Unit and integration tests across core and modules. Use them to verify behavioral compatibility.
  • AabSemantics.TestCore holds shared test infrastructure and fixture data reused by the other test projects.

Build and run

• Requires the .NET 8 SDK. Visual Studio 2022 (with the .NET desktop development workload) or the dotnet CLI both work; Visual Studio 2019 cannot build the net8.0 projects.
• Build: dotnet build Code/AabSemantics.sln. NuGet restore happens automatically.
• Test: dotnet test Code/AabSemantics.sln.
• Run samples from Code/Samples/* to validate expected behavior after changes.
• Building the WPF client and WPF extension requires Windows; the rest of the solution is cross-platform.

Technology notes

• All projects use the SDK-style project format with PackageReference. There is no packages.config and no Code/packages folder.
• Target frameworks by layer:
  • netstandard2.0: core (AabSemantics, Inventor.Algorithms) and all modules — keep them portable.
  • net8.0: EF extension, REST client, samples, and tests.
  • net8.0-windows: WPF client and WPF extension.
• Entity Framework 6.5.2 is referenced by AabSemantics.Extensions.EF and Sample09. Avoid uncoordinated major upgrades.
• The WPF client targets net8.0-windows, not .NET Framework.
• Shared metadata (Authors, Company, Product, Copyright, Version, license, repository URL) lives in the root Directory.Build.props. Do not repeat it in individual projects; override a property only when a project genuinely differs (as the core library does for PackageId, Version and Description).
• Code/Tests/Directory.Build.props adds IsPackable=false and the NUnit / test SDK package references to every test project. It explicitly imports the root file, because MSBuild only applies the nearest Directory.Build.props.
• The solution uses Central Package Management: every package version is declared once as a PackageVersion in the root Directory.Packages.props. A PackageReference in a project carries only Include (plus metadata such as PrivateAssets) and must not specify Version — doing so is an error under CPM.
• To add a package: add a PackageVersion to Directory.Packages.props, then reference it without a version from the project that needs it.
• Transitive pinning (CentralPackageTransitivePinningEnabled) is deliberately off, so transitive dependencies still resolve to whatever their parent package requires.

Architectural overview

• The core (AabSemantics) defines the semantic network, concepts, statements, questions, answers, and text generation/localization.
• Modules extend the core with domain-specific statements, questions, and processing.
• Extensions integrate with EF and WPF for persistence and UI.
• Clients expose the engine via REST or present a WPF UX.

Backwards compatibility priorities

When modifying code, maintain compatibility in:

• Public contracts in Core/AabSemantics/Interfaces/* and other public types that are consumed by modules/clients.
• Serialization contracts in Core/AabSemantics/Serialization/* and any wire formats used by REST clients.
• Resource keys and localization structure in Localization/*.

Breaking changes must be isolated behind adapters or versioned DTOs. Prefer additive changes over mutating existing contracts.

Testing expectations

• Tests use NUnit 4. Run them with dotnet test Code/AabSemantics.sln after any non-trivial change; the full suite is fast (a few seconds) and is expected to be green.
• Add tests when changing behavior, fixing bugs, or adding features.
• Keep tests deterministic; avoid time- or randomness-dependent assertions.

Coding standards (C#)

• Favor clarity and explicitness over cleverness. Prefer descriptive names over abbreviations.
• Keep functions small with clear responsibilities; use early returns instead of deep nesting.
• Minimize try/catch; handle only anticipated exceptions meaningfully.
• Document only non-obvious rationale, invariants, or edge cases. Avoid redundant comments.
• Match existing formatting; do not reformat unrelated code in the same edit.

Contributing workflow

• Use feature branches. Keep edits scoped and reviewable.
• Write clear commit messages summarizing the change and impact (present tense, imperative mood).
• For multi-file changes, structure commits logically (e.g., API addition, then implementation, then tests).

Areas that require extra care

• Core/AabSemantics/Interfaces: Treat as stable API; prefer extension points over edits.
• Core/AabSemantics/Serialization: Do not change existing DTO shapes without versioning and migration.
• Extensions/EF: Ensure model mappings remain consistent; migrations should be explicit if added.
• Clients/*: Keep endpoints stable; changing REST contracts requires versioning.
• Localization/*: Preserve resource keys; adding is fine, renaming requires a cross-repo audit.

Guidance for AI agents (Cursor / automated assistants)

Follow these rules strictly when making changes:

• Make the smallest viable edit that achieves the goal. Do not refactor unrelated code.
• Preserve existing indentation style and width; do not mix tabs and spaces.
• Maintain file encoding and line endings; do not introduce BOM changes.
• If adding new files, place them in the most specific directory (e.g., a new module under Code/Modules/<ModuleName>; a shared contract under Core/AabSemantics/Interfaces).
• Prefer additive, backwards-compatible changes. Avoid breaking public APIs and serialization.
• Update or add tests for any behavioral change; run tests locally.
• Keep comments concise and only for non-obvious context.
• Do not upgrade third-party packages without an explicit instruction.
• Avoid introducing long-lived feature flags unless specified; keep configuration simple.
• For REST work, document new endpoints and payloads in the controllers' XML docs; they surface through the Swagger UI, which is enabled in the Development environment.

When uncertain:

• Search for usage across Core, Modules, Extensions, Clients, Samples, and Tests to assess impact.
• Prefer introducing new interfaces or overloads rather than mutating existing ones.

How to add a new module (quick checklist)

1. Create a project under Code/Modules/AabSemantics.Modules.<YourModuleName> following existing module csproj patterns (netstandard2.0).
2. Define statements, questions, and answers types extending core abstractions.
3. Register module with the semantic network composition where needed.
4. Add unit tests under Code/Tests/AabSemantics.Modules.<YourModuleName>.Tests, reusing AabSemantics.TestCore.
5. Add a minimal sample under Code/Samples/ if appropriate.

How to extend the REST client (quick checklist)

1. Add a new controller under Code/Clients/AabSemantics.SimpleRestClient/Controllers.
2. Reuse core/module services; avoid duplicating business logic.
3. Ensure request/response models are versioned or additive.
4. Add sample requests to the controller's XML docs so they appear in Swagger.

License and provenance

• See LICENSE at the repository root for licensing.

Document maintenance

• Keep this guide accurate with any project-wide or process changes.
• If major architecture evolves, update the overview and the “Areas that require extra care” section.