OpenSAIL.Core 0.0.0.1

🚀 OpenSAIL — Semantic API Intent Layer

OpenSAIL (Semantic API Intent Layer) is a lightweight and extensible protocol to describe the intent of your REST endpoints using natural language — enabling seamless integration with Large Language Models (LLMs), smart frontends, and CLI agents without cluttering your controller code.

✨ Why OpenSAIL?

• 🔌 Zero-intrusion: no attributes or controller annotations
• 🧠 x-ai-* metadata injection directly into your Swagger/OpenAPI output
• 📄 Managed via a standalone sail.manifest.json file
• 🤖 LLM-aware: perfect for prompt-routing, Copilot-style tools, and AI agents
• 🛠️ Fully compatible with existing REST APIs and Swagger tooling

📦 Installation

🔜 Via NuGet (coming soon)

dotnet add package OpenSAIL.Core

⚙️ How to Use

1. Add the package to your ASP.NET Web API project

dotnet add package OpenSAIL.Core

2. Create a sail.manifest.json file in your project root

{
  "endpoints": [
    {
      "path": "/weatherforecast",
      "method": "get",
      "intent": "get_weatherforecast",
      "description": "List all weather predictions for a specific day.",
      "meaning": "The response is a JSON array with date, summary, and temperature in Celsius.",
      "examples": [
        "Is today going to be cold?",
        "What is the weather prediction for tomorrow?"
      ]
    }
  ]
}

3. Register it in Program.cs

builder.Services.AddSwaggerGen();
builder.Services.AddAiExtensions("sail.manifest.json");

var app = builder.Build();

app.UseSwagger(); // Only needed if you want to expose the enriched openapi.json
app.MapControllers();
app.Run();

📄 Manifest Structure (sail.manifest.json)

{
  "endpoints": [
    {
      "path": "/route",
      "method": "get|post|put|delete",
      "intent": "action_identifier",
      "description": "Human-readable explanation of what the endpoint does.",
      "meaning": "What the response represents (useful for AI interpretation).",
      "examples": [
        "Natural phrases a user might say"
      ]
    }
  ]
}

🧠 Result

The openapi.json will include injected semantic metadata like:

"x-ai-intent": "get_weatherforecast",
"x-ai-description": "List all weather predictions for a specific day.",
"x-ai-meaning": "The response is a JSON array with date, summary, and temperature in Celsius.",
"x-ai-examples": [
  "Is today going to be cold?",
  "What is the weather prediction for tomorrow?"
]

This enriched spec can be consumed by:

• LLM Agents (LangChain, AutoGen, Guidance)
• Smart frontends (useApi() hooks, prompt suggesters)
• CLI wrappers or prompt-based workflows

🔐 License

MIT

🛣️ Roadmap

• OpenAPI 3.0+ support
• Manifest-based metadata injection
• Semantic enrichment for Swagger
• JSON Schema validation for manifest
• CLI: generate manifest from OpenAPI
• NuGet publication
• Integration example with LLM agent or prompt-router

Built with ❤️ and precision by Pedro Arruda
Envisioned for the next generation of API–AI interoperability.