Skip to content

Commit 151ee76

Browse files
jongallowayjongalloway
authored
Merge pull request #11 from jongalloway/copilot/fix-10
Set up custom-instructions.md for NLWebNet repository
2 parents e84b154 + 2b470c0 commit 151ee76

File tree

1 file changed

+226
-0
lines changed

1 file changed

+226
-0
lines changed

‎custom-instructions.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Custom Instructions for NLWebNet
2+
3+
This document provides guidance for AI assistants working with the NLWebNet codebase. Please follow these instructions when providing development assistance, code suggestions, or modifications.
4+
5+
## Project Overview
6+
7+
**NLWebNet** is a .NET implementation of the [NLWeb protocol](https://github.com/microsoft/NLWeb) for building natural language web interfaces.
8+
9+
### NuGet Package Development
10+
11+
**This library is being developed for eventual production use and follows .NET best practices.**
12+
13+
- **Purpose**: To create a production-quality implementation of the NLWeb protocol for .NET applications
14+
- **Current status**: Early alpha prerelease (0.1.0-alpha.3) - not yet production ready
15+
- **Development goal**: Production-ready library with high code quality standards
16+
- **Demo application**: Simple reference implementation showcasing library capabilities
17+
- **Target audience**: .NET developers building natural language web interfaces
18+
19+
## Technology Stack
20+
21+
- **.NET 9.0** - Latest .NET version with modern features
22+
- **ASP.NET Core** - Web framework with Minimal APIs
23+
- **Blazor Web App** - For the demo application
24+
- **Microsoft.Extensions.AI** - AI service abstractions
25+
- **Model Context Protocol (MCP)** - For enhanced AI integration
26+
- **MSTest** - Testing framework
27+
- **NSubstitute** - Mocking framework for unit tests
28+
29+
## Architecture Patterns
30+
31+
### 1. Minimal API Approach
32+
- **Primary approach**: Uses **Minimal APIs** for modern, lightweight endpoints
33+
- **Legacy support**: Traditional controllers still present but being phased out
34+
- Endpoints are organized in static classes: `AskEndpoints`, `McpEndpoints`
35+
- Extension methods provide clean endpoint mapping: `app.MapNLWebNet()`
36+
- Both `app.MapNLWebNet()` (minimal APIs) and `app.MapNLWebNetControllers()` (legacy) available
37+
38+
### 2. Dependency Injection
39+
- Follows standard .NET DI patterns
40+
- Extension methods for service registration: `services.AddNLWebNet()`
41+
- Interface-based design with clear service contracts
42+
- Supports custom backend implementations via generics
43+
44+
### 3. Service Layer Architecture
45+
```
46+
Controllers/Endpoints → Services → Data Backends
47+
↘ MCP Integration
48+
```
49+
50+
Key interfaces:
51+
- `INLWebService` - Main orchestration service
52+
- `IDataBackend` - Data retrieval abstraction
53+
- `IQueryProcessor` - Query processing logic
54+
- `IResultGenerator` - Response generation
55+
- `IMcpService` - Model Context Protocol integration
56+
57+
### 4. Configuration Pattern
58+
- Uses `NLWebOptions` for strongly-typed configuration
59+
- Supports configuration binding from `appsettings.json`
60+
- User secrets for sensitive data (API keys)
61+
- Environment-specific configurations
62+
63+
### 5. Architectural Migration
64+
**Important**: The project is transitioning from traditional MVC controllers to Minimal APIs.
65+
66+
- **Preferred**: Use `Endpoints/` classes with static mapping methods
67+
- **Legacy**: `Controllers/` still exists but should not be extended
68+
- **Extension methods**: Both approaches supported via `MapNLWebNet()` (minimal APIs) and `MapNLWebNetControllers()` (legacy)
69+
- **New development**: Always use Minimal API patterns in the `Endpoints/` directory
70+
71+
## Code Conventions
72+
73+
### Naming and Structure
74+
- **Namespace**: All code under `NLWebNet` namespace
75+
- **Models**: Request/response DTOs with JSON serialization attributes
76+
- **Services**: Interface + implementation pattern (`IService` → `Service`)
77+
- **Extensions**: Static extension classes for framework integration
78+
- **Endpoints**: Static classes with minimal API mapping methods (preferred)
79+
- **Controllers**: Traditional MVC controllers (legacy, being phased out)
80+
81+
### C# Style Guidelines
82+
- **Nullable reference types** enabled (`<Nullable>enable</Nullable>`)
83+
- **Implicit usings** enabled for common namespaces
84+
- **XML documentation** for all public APIs
85+
- **Data annotations** for request validation
86+
- **JSON property names** in snake_case for protocol compliance
87+
88+
### File Organization
89+
```
90+
src/NLWebNet/
91+
├── Models/ # Request/response DTOs
92+
├── Services/ # Business logic interfaces/implementations
93+
├── Endpoints/ # Minimal API endpoint definitions (preferred)
94+
├── Extensions/ # DI and middleware extensions
95+
├── Controllers/ # Legacy MVC controllers (being phased out)
96+
├── MCP/ # Model Context Protocol integration
97+
└── Middleware/ # Custom middleware components
98+
```
99+
100+
## NLWeb Protocol Implementation
101+
102+
### Core Concepts
103+
- **Three query modes**: `List`, `Summarize`, `Generate`
104+
- **Streaming support**: Real-time response delivery
105+
- **Query context**: Previous queries and decontextualization
106+
- **Site filtering**: Subset targeting within data backends
107+
108+
### Request/Response Flow
109+
1. Validate incoming `NLWebRequest`
110+
2. Process query through `IQueryProcessor`
111+
3. Retrieve data via `IDataBackend`
112+
4. Generate response using `IResultGenerator`
113+
5. Return `NLWebResponse` with results
114+
115+
### MCP Integration
116+
- Supports core MCP methods: `list_tools`, `list_prompts`, `call_tool`, `get_prompt`
117+
- Parallel endpoint structure: `/ask` and `/mcp` with shared logic
118+
- Tool and prompt template management
119+
120+
## Testing Approach
121+
122+
### Unit Testing
123+
- **39 unit tests** with 100% pass rate (current standard)
124+
- **NSubstitute** for mocking dependencies
125+
- **MSTest** framework with `[TestMethod]` attributes
126+
- Focus on service layer and business logic testing
127+
128+
### Integration Testing
129+
- **Manual testing** preferred over automated integration tests
130+
- **Comprehensive guides** in `/doc/manual-testing-guide.md`
131+
- **Sample requests** in `/doc/sample-requests.http` for IDE testing
132+
- **Demo application** for end-to-end validation
133+
134+
### Testing Conventions
135+
- Test classes named `[ClassUnderTest]Tests`
136+
- Arrange-Act-Assert pattern
137+
- Mock external dependencies (AI services, data backends)
138+
- Test both success and error scenarios
139+
140+
## Development Practices
141+
142+
### CI/CD Pipeline
143+
- **GitHub Actions** for automated builds and testing
144+
- **NuGet package** generation and validation
145+
- **Release automation** with version tagging
146+
- **Security scanning** for vulnerable dependencies
147+
148+
### Build and Packaging
149+
- **Deterministic builds** for reproducible packages
150+
- **Symbol packages** (.snupkg) for debugging support
151+
- **Source Link** integration for GitHub source navigation
152+
- **Package validation** scripts for quality assurance
153+
154+
### Documentation Standards
155+
- **Comprehensive README** with usage examples
156+
- **XML documentation** for all public APIs
157+
- **OpenAPI specification** generated automatically
158+
- **Manual testing guides** for validation procedures
159+
160+
## AI Service Integration
161+
162+
### Microsoft.Extensions.AI Pattern
163+
- Use `Microsoft.Extensions.AI` abstractions for AI service integration
164+
- Support multiple AI providers (Azure OpenAI, OpenAI API)
165+
- Configuration-driven AI service selection
166+
- Async/await patterns for AI service calls
167+
168+
### Error Handling
169+
- **Graceful degradation** when AI services are unavailable
170+
- **Fallback responses** for service failures
171+
- **Proper exception handling** with meaningful error messages
172+
- **Logging** for debugging and monitoring
173+
174+
## Common Patterns and Best Practices
175+
176+
### When Adding New Features
177+
1. **Start with interfaces** - Define contracts before implementations
178+
2. **Add configuration options** to `NLWebOptions` if needed
179+
3. **Include unit tests** - Maintain the 100% pass rate standard
180+
4. **Update documentation** - XML docs and README as appropriate
181+
5. **Consider MCP integration** - How does this fit with MCP protocol?
182+
183+
### When Modifying Endpoints
184+
1. **Use Minimal APIs** - Prefer `Endpoints/` classes over `Controllers/`
185+
2. **Maintain protocol compliance** - Follow NLWeb specification
186+
3. **Add OpenAPI documentation** - Use `.WithSummary()` and `.WithDescription()`
187+
4. **Include error responses** - Proper status codes and problem details
188+
5. **Test with sample requests** - Update manual testing guides
189+
190+
### When Adding Dependencies
191+
1. **Prefer Microsoft.Extensions.*** - Use standard .NET abstractions
192+
2. **Check for existing alternatives** - Avoid duplicate functionality
193+
3. **Update project files** - Include in main library and test projects
194+
4. **Validate package size** - Keep library lightweight
195+
196+
## Limitations and Current Implementation Status
197+
198+
### Current Implementation Status
199+
- **Early alpha prerelease** - Core functionality implemented, not yet production ready
200+
- **Mock data backend** as default - Real data source integrations can be implemented via `IDataBackend`
201+
- **Basic AI integration** - Extensible via Microsoft.Extensions.AI patterns
202+
- **Authentication framework** - Ready for implementation based on application requirements
203+
- **Code quality standards** - Production-level code quality maintained throughout development
204+
205+
### Performance Considerations
206+
- **Streaming responses** for better perceived performance
207+
- **Async/await** throughout for scalability
208+
- **Minimal allocations** where possible
209+
- **Configuration caching** for frequently accessed settings
210+
211+
### Deployment Considerations
212+
- **Requires .NET 9.0** - Latest framework dependency for modern features
213+
- **Early prerelease status** - Not yet ready for production deployment
214+
- **Production-quality code** - Library being developed with production standards
215+
- **Demo app simplicity** - Reference implementation kept simple for clarity
216+
217+
## When to Seek Clarification
218+
219+
Ask for guidance when:
220+
- **Breaking changes** to public APIs are needed
221+
- **New external dependencies** are required
222+
- **Significant architectural changes** are proposed
223+
- **Protocol compliance** questions arise
224+
- **Production deployment** patterns need to be established
225+
226+
Remember: This library is being developed with production-quality standards, though it is currently in early prerelease and not yet ready for production use. All code additions and edits should maintain production-level quality as the project works toward its goal of becoming a production-ready NLWeb protocol implementation for .NET applications.

0 commit comments

Comments
 (0)