Skip to content

Commit 05e98b9

Browse files
Copilotjongalloway
Copilot
and
jongalloway
committed
Create comprehensive custom-instructions.md for NLWebNet
Co-authored-by: jongalloway <[email protected]>
1 parent 9c199b6 commit 05e98b9

File tree

1 file changed

+223
-0
lines changed

1 file changed

+223
-0
lines changed

‎custom-instructions.md‎

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

0 commit comments

Comments
 (0)