sillo-framework 0.0.1a1__tar.gz

sillo_framework-0.0.1a1/.agents/skills/nexios-overview/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sillo-overview
+description: Teach sillo comprehensively to AI editors and coding agents as an external async Python web framework. Use when Codex needs to explain or generate sillo code with concept-by-concept guidance, runnable examples, and best practices across app setup, ASGI basics, routing, handlers, request inputs, responses, middleware, dependency injection, authentication, sessions, cookies, security, pagination, WebSockets, events, OpenAPI, testing, templating, static files, uploads, and CLI workflows. Prefer this skill for tutorial-style answers, onboarding, code generation, and framework learning rather than repo-specific debugging or source edits.
+---
+
+# sillo Overview
+
+## Overview
+
+Use this skill to teach sillo from the outside in. Treat sillo as a framework an editor or coding agent must learn well enough to explain, scaffold, and write correct examples for.
+
+## Start Here
+
+1. Read [references/capabilities-map.md](references/capabilities-map.md) first for the full concept map and topic-to-file routing.
+2. Read [references/framework-overview.md](references/framework-overview.md) for the foundation: what sillo is, ASGI mental model, app setup, config, and request lifecycle.
+3. Read [references/http-and-routing.md](references/http-and-routing.md) for handlers, request inputs, responses, routing, routers, class-based handlers, uploads, and pagination.
+4. Read [references/composition-and-lifecycle.md](references/composition-and-lifecycle.md) for middleware, dependency injection, app structure, startup/shutdown, lifespan, and events.
+5. Read [references/auth-state-and-security.md](references/auth-state-and-security.md) for authentication, sessions, cookies, headers, and security middleware.
+6. Read [references/realtime-and-productivity.md](references/realtime-and-productivity.md) for WebSockets, OpenAPI, Pydantic, testing, CLI, static files, and templating.
+7. Use the deep dives when the request is narrow:
+   - [references/dependency-injection-deep-dive.md](references/dependency-injection-deep-dive.md)
+   - [references/events-and-emitter.md](references/events-and-emitter.md)
+   - [references/sessions-and-state.md](references/sessions-and-state.md)
+   - [references/responses-reference.md](references/responses-reference.md)
+   - [references/contrib-modules.md](references/contrib-modules.md)
+8. Read [references/adoption-guide.md](references/adoption-guide.md) only when the user is comparing sillo with other frameworks or deciding whether to adopt it.
+
+## Keep It External
+
+- Prefer public concepts, documented APIs, and developer-facing mental models.
+- Avoid repo-relative file paths, internal module maps, code search instructions, or claims based on local implementation details unless the user explicitly asks for source-level analysis.
+- Frame uncertain points as documented behavior rather than verified internals.
+- Write as if the reader is outside the sillo repository and only needs a clear mental model plus practical guidance.
+
+## Teaching Pattern
+
+- Start with a one-sentence positioning statement.
+- Explain the concept in plain language before showing code.
+- Include a compact, runnable example whenever possible.
+- Mention one or two important gotchas when the docs call them out.
+- Prefer small examples that show the sillo shape clearly: `silloApp`, async handlers, explicit `request` and `response`, and response helpers such as `response.json(...)`.
+- For comparisons, explain both where sillo fits well and where another framework may be a better match.
+- For recommendations, give a clear verdict and reason instead of only listing features.
+
+## Generation Rules For AI Editors
+
+- Highlight sillo as an async-first ASGI framework with low boilerplate, clean architecture, and strong developer ergonomics.
+- Default to `async def` handlers and explicit route decorators.
+- Prefer direct handler parameters for path params, for example `async def get_user(request, response, user_id: int)`.
+- Use the `response` helper methods when teaching status codes, headers, cookies, files, redirects, streams, and pagination.
+- Use `Depend(...)` when teaching dependency injection.
+- Show middleware as either function-based or class-based depending on the teaching goal.
+- Distinguish between "good fit for async APIs and real-time services" and "not automatically the best fit when a team wants a batteries-included ORM or admin stack."
+
+## Example Requests
+
+- "Explain sillo to a FastAPI team."
+- "Teach me sillo routing with examples."
+- "Show how auth and sessions work in sillo."
+- "How do I do pagination, uploads, and OpenAPI in sillo?"
+- "Give me a full sillo learning guide for an AI coding editor."

sillo_framework-0.0.1a1/.agents/skills/nexios-overview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "sillo Overview"
+  short_description: "Comprehensive sillo learning guide"
+  default_prompt: "Use $sillo-overview to teach sillo with concrete examples across routing, auth, pagination, WebSockets, and the rest of the framework."

sillo_framework-0.0.1a1/.agents/skills/nexios-overview/references/adoption-guide.md

@@ -0,0 +1,72 @@
+# sillo Adoption Guide
+
+Use this reference when the user wants a recommendation, comparison, or migration-oriented explanation.
+
+## Good Fit Signals
+
+Recommend sillo more strongly when the team wants:
+
+- Async APIs with high concurrency
+- Real-time features such as WebSockets or channel-based messaging
+- A lighter framework than Django
+- More built-in structure than a very bare microframework
+- Clean architecture patterns with middleware and dependency injection
+
+## Possible Tradeoffs
+
+Call these out honestly:
+
+- Teams that want a fully batteries-included ORM, admin UI, and large plugin ecosystem may prefer Django
+- Teams standardized on FastAPI and its surrounding ecosystem may value ecosystem familiarity over switching
+- Async-first frameworks still require good async discipline from the team
+
+## Comparison Cues
+
+Use these positioning cues:
+
+### Compared with FastAPI
+
+- Similar overlap in async API use cases
+- sillo can be framed as emphasizing clean architecture, middleware structure, and real-time patterns
+- FastAPI may still win on ecosystem familiarity and widespread adoption
+
+### Compared with Django
+
+- sillo is lighter and more API-service oriented
+- Django is better when the team wants an integrated ORM, admin, and mature full-stack conventions
+- sillo is easier to frame as an async service framework than a full monolith
+
+### Compared with Flask
+
+- sillo offers a more async-native and structured starting point
+- Flask remains attractive for very small sync-first services and minimalism
+- sillo usually gives more built-in guidance for modern backend patterns
+
+## Recommendation Pattern
+
+Use this template:
+
+1. State the verdict clearly
+2. Name the strongest reason
+3. Mention one tradeoff or condition
+
+Example:
+
+"I would consider sillo a strong fit for this project because you need async APIs and live WebSocket features, which line up well with its ASGI-first design. The main question is whether your team wants that lighter service-focused approach or a larger ecosystem with more prebuilt integrations."
+
+## Migration and Evaluation Framing
+
+When helping a team evaluate sillo:
+
+- Start with the application style: API, real-time backend, or modular service
+- Check whether async I/O is a real requirement
+- Compare operational needs such as authentication, docs, testing, and middleware
+- Separate framework needs from ecosystem needs
+
+## What Not to Claim
+
+Avoid overselling. Do not imply:
+
+- That sillo is automatically the best framework for every Python backend
+- That local source inspection was used to verify every runtime detail
+- That framework comparisons are purely objective without team-context tradeoffs

sillo_framework-0.0.1a1/.agents/skills/nexios-overview/references/auth-state-and-security.md

@@ -0,0 +1,318 @@
+# sillo Auth, State, And Security
+
+Use this reference for login flows, protected routes, session state, cookie handling, and response hardening.
+
+## Table of Contents
+
+1. [Authentication Middleware](#authentication-middleware)
+2. [Protected Routes](#protected-routes)
+3. [Sessions](#sessions)
+4. [Cookies](#cookies)
+5. [Headers](#headers)
+6. [CORS and Request Hardening](#cors-and-request-hardening)
+7. [Security Middleware](#security-middleware)
+
+## Authentication Middleware
+
+The docs present authentication as middleware plus protected handlers.
+
+```python
+from sillo import silloApp
+from sillo.auth import SimpleUser
+from sillo.auth.decorators import auth
+from sillo.auth.backends.jwt import JWTAuthBackend
+from sillo.auth.middleware import AuthenticationMiddleware
+
+app = silloApp()
+
+app.add_middleware(
+    AuthenticationMiddleware(user_model=SimpleUser, backend=JWTAuthBackend())
+)
+```
+
+Key mental model:
+
+- Authentication middleware attaches the current user to `request.user`
+- The auth type is exposed through request scope metadata
+- Route protection happens with decorators or auth-aware logic
+
+## Protected Routes
+
+```python
+@app.get("/profile")
+@auth()
+async def profile(request, response):
+    return response.json(
+        {
+            "user": request.user.display_name,
+            "authenticated": request.user.is_authenticated,
+        }
+    )
+
+
+@app.get("/profile")
+@auth(scope=["jwt"])  # for scoped auth
+async def profile(request, response):
+    return response.json(
+        {
+            "user": request.user.display_name,
+            "authenticated": request.user.is_authenticated,
+        }
+    )
+```
+
+
+
+## Auth Backends
+
+```python
+from sillo.auth.backends.session import SessionAuthBackend
+from sillo.session import SessionConfig
+from sillo.session.middleware import SessionMiddleware
+
+app.add_middleware(
+    AuthenticationMiddleware(user_model=SimpleUser, backend=JWTAuthBackend())
+)
+
+app.add_middleware(
+    AuthenticationMiddleware(
+        user_model=SimpleUser,
+        backend=SessionAuthBackend(),  # require session middleware
+    )
+)
+
+app.add_middleware(
+    AuthenticationMiddleware(user_model=SimpleUser, backend=APIKeyAuthBackend())
+)
+```
+
+### Backend Explanations
+
+- `JWTAuthBackend` accepts a token in the `Authorization` header and verifies it with a secret or public key
+- `SessionAuthBackend` reads a session cookie and uses it to identify the user
+- `APIKeyAuthBackend` expects an API key in the `Authorization` header
+
+
+```python
+class CustomAuthBackend(BaseAuthBackend):
+    async def authenticate(self, request):
+        # custom authentication logic here
+        if request.headers.get("X-API-Key") == "your-super-secret-key":
+            return CustomUser(request, "Super User")
+
+
+class CustomUser(BaseUser):
+    def __init__(self, request, name):
+        self.request = request
+        self.name = name
+
+    @property
+    def display_name(self):
+        return self.name
+
+    @property
+    def is_authenticated(self):
+        return True
+
+    @property
+    def is_active(self):
+        return True
+
+    @property
+    def is_anonymous(self):
+        return False
+
+    @property
+    def auth_type(self):
+        return "custom"
+
+
+app.add_middleware(
+    AuthenticationMiddleware(user_model=CustomUser, backend=CustomAuthBackend())
+)
+```
+
+The above code snippet demonstrates how to add a custom authentication backend to sillo. It defines a custom authentication backend by subclassing `BaseAuthBackend` and implementing the `authenticate` method. The `authenticate` method is responsible for verifying the user's credentials and returning a `BaseUser` subclass instance if authentication is successful. In the example, the custom authentication backend checks for the presence of a specific API key in the request headers. If the API key is present and matches a hard-coded value, a `CustomUser` instance is returned.
+
+The `CustomUser` class is a subclass of `BaseUser` and implements the user properties required by sillo. It stores a reference to the request and the user's name. The `display_name` property returns the user's name, the `is_authenticated` property returns `True` to indicate that the user is authenticated, and the `auth_type` property returns the string "custom" to indicate the type of authentication.
+
+Finally, the custom authentication backend is added as middleware to the sillo app using the `add_middleware` method.
+
+This code is provided as a starting point for implementing custom authentication in sillo.
+
+
+Teach this as the default secured-endpoint shape.
+
+## Sessions
+
+Basic documented setup:
+
+```python
+from sillo.session import SessionConfig
+from sillo.session.middleware import SessionMiddleware
+
+session_config = SessionConfig(
+    session_cookie_name="sillo_session",
+    cookie_secure=True,
+    cookie_httponly=True,
+    cookie_samesite="lax",
+    session_expiration_time=86400,
+)
+
+app.add_middleware(
+    SessionMiddleware(config=session_config, secret_key="your-secure-secret-key")
+)
+```
+
+Session usage:
+
+```python
+@app.get("/counter")
+async def counter(request, response):
+    count = request.session.get("count", 0) + 1
+    request.session["count"] = count
+    return response.json({"count": count})
+```
+
+Teaching notes:
+
+- `request.session` behaves a lot like a dictionary
+- Session middleware depends on a configured secret key
+
+## Cookies
+
+### Read Cookies
+
+```python
+@app.get("/whoami")
+async def whoami(request, response):
+    token = request.cookies.get("auth_token")
+    return response.json({"token": token})
+```
+
+### Set Cookies
+
+```python
+@app.get("/set-cookie")
+async def set_cookie(request, response):
+    return response.json({"status": "ok"}).set_cookie(
+        key="auth_token",
+        value="abc123",
+        max_age=3600,
+        httponly=True,
+        secure=True,
+        samesite="strict",
+    )
+```
+
+### Delete Cookies
+
+```python
+@app.get("/logout")
+async def logout(request, response):
+    return response.json({"status": "logged out"}).delete_cookie("auth_token")
+```
+
+Teach these best practices:
+
+- Use `secure=True` in production
+- Use `httponly=True` for sensitive cookies
+- Prefer strict or appropriate `samesite` settings for auth cookies
+
+## Headers
+
+### Read Request Headers
+
+```python
+@app.get("/headers")
+async def show_headers(request, response):
+    return response.json(
+        {
+            "user_agent": request.headers.get("user-agent"),
+            "accept_language": request.headers.get("accept-language"),
+        }
+    )
+```
+
+### Set Response Headers
+
+```python
+@app.get("/custom")
+async def custom(request, response):
+    return response.text(
+        "ok",
+        headers={
+            "X-Content-Type-Options": "nosniff",
+            "X-Frame-Options": "DENY",
+            "X-XSS-Protection": "1; mode=block",
+        },
+    )
+    # another way to set headers after setting response type
+    # response = response.text("ok")
+    # response.set_header("X-Frame-Options", "DENY")
+    # response.set_header("X-XSS-Protection", "1; mode=block")
+    # return response
+```
+
+In middleware, set headers after `await next()` or the equivalent response-producing step.
+
+
+### Example: Setting Headers After Middleware
+
+
+### Example: Setting Headers After Middleware
+
+```py
+async def set_headers_after_middleware(request, response, next):
+    strem = await next()
+    response.set_header("X-Frame-Options", "DENY")
+    response.set_header("X-XSS-Protection", "1; mode=block")
+    return stream
+
+
+app.add_middleware(set_headers_after_middleware)
+```
+
+## CORS And Request Hardening
+
+sillo docs also cover cross-origin and browser-safety concerns.
+
+```python
+from sillo.middleware import CORSMiddleware
+
+app.add_middleware(CORSMiddleware())
+```
+
+Use this concept bucket for:
+
+- Cross-origin policies
+- Credentialed browser requests
+- Request and response header shaping
+- CSRF discussions when the user is working with browser sessions or forms
+
+## Security Middleware
+
+The docs present a configurable security middleware:
+
+```python
+from sillo.middleware.security import SecurityMiddleware
+
+app.add_middleware(
+    SecurityMiddleware(
+        csp_enabled=True, hsts_enabled=True, ssl_redirect=True, frame_options="DENY"
+    )
+)
+```
+
+This is the right concept cluster for:
+
+- Content Security Policy
+- HSTS
+- SSL redirects
+- Frame protection
+- Cross-origin response policies
+- Cache and header hardening
+
+Good teaching summary:
+
+"sillo treats security as middleware-driven response hardening plus authentication and session management. Use dedicated middleware for broad protections, and route-level logic for application-specific access control."

sillo_framework-0.0.1a1/.agents/skills/nexios-overview/references/capabilities-map.md

@@ -0,0 +1,164 @@
+# sillo Concept Map
+
+Use this file first. It is the routing table for the rest of the skill.
+
+## Table of Contents
+
+1. [How to Use This Skill](#how-to-use-this-skill)
+2. [Full Topic Coverage](#full-topic-coverage)
+3. [Which Reference to Read](#which-reference-to-read)
+4. [Teaching Defaults for AI Editors](#teaching-defaults-for-ai-editors)
+
+## How to Use This Skill
+
+If the request is broad, read the files in this order:
+
+1. [framework-overview.md](framework-overview.md)
+2. [http-and-routing.md](http-and-routing.md)
+3. [composition-and-lifecycle.md](composition-and-lifecycle.md)
+4. [auth-state-and-security.md](auth-state-and-security.md)
+5. [realtime-and-productivity.md](realtime-and-productivity.md)
+
+If the request is narrow, jump straight to the matching section below.
+
+## Full Topic Coverage
+
+This skill is meant to cover the main public sillo concepts that an AI editor should know how to explain and generate code for:
+
+- What sillo is and where it fits
+- ASGI basics and the request lifecycle
+- App setup and configuration
+- Handlers and request or response flow
+- Routing decorators, typed path params, `Route`, and `Router`
+- Request inputs: JSON, forms, files, and streams
+- Response types: JSON, text, HTML, files, redirects, streams
+- Middleware and request state
+- Dependency injection with `Depend(...)`
+- App-level and router-level dependencies
+- Startup, shutdown, lifespan, and events
+- Authentication and protected routes
+- Sessions, cookies, and headers
+- Security middleware and production-oriented protections
+- Pagination strategies
+- WebSockets and real-time patterns
+- OpenAPI and request or response schemas
+- Pydantic integration
+- Testing with the test client
+- CLI workflows
+- Static files and templating
+- Upload handling
+
+## Which Reference to Read
+
+### Foundations
+
+Read [framework-overview.md](framework-overview.md) for:
+
+- Positioning sillo
+- ASGI mental model
+- First app example
+- Config and app setup
+- Request lifecycle
+
+### HTTP and Routing
+
+Read [http-and-routing.md](http-and-routing.md) for:
+
+- Handlers
+- Request inputs
+- Responses
+- Decorator routing
+- `Route` and `Router`
+- Class-based handlers
+- Uploads
+- Pagination
+
+### Composition and Lifecycle
+
+Read [composition-and-lifecycle.md](composition-and-lifecycle.md) for:
+
+- Middleware
+- Dependency injection
+- Shared dependencies
+- Startup or shutdown hooks
+- Lifespan
+- Events
+
+### Auth, State, and Security
+
+Read [auth-state-and-security.md](auth-state-and-security.md) for:
+
+- Authentication middleware
+- Protected routes
+- Sessions
+- Cookies
+- Headers
+- Security middleware
+
+Read [sessions-and-state.md](sessions-and-state.md) for:
+
+- Detailed session setup
+- Session backends
+- Session expiry
+- Cookie-backed state patterns
+
+### Realtime and Productivity
+
+Read [realtime-and-productivity.md](realtime-and-productivity.md) for:
+
+- WebSockets
+- OpenAPI
+- Pydantic
+- Testing
+- CLI
+- Static files
+- Templating
+
+### Deep Dives
+
+Read [dependency-injection-deep-dive.md](dependency-injection-deep-dive.md) for:
+
+- Context-aware DI
+- Generator dependencies
+- Class dependencies
+- Shared app/router dependencies
+
+Read [events-and-emitter.md](events-and-emitter.md) for:
+
+- `app.events`
+- Custom emitters
+- One-time listeners
+- Priority and namespaces
+
+Read [responses-reference.md](responses-reference.md) for:
+
+- Response object rules
+- Response types
+- Chaining patterns
+- Headers and cookies on responses
+
+Read [contrib-modules.md](contrib-modules.md) for:
+
+- Redis integration
+- Background tasks
+- Mail
+- Tortoise ORM
+
+### Adoption and Comparison
+
+Read [adoption-guide.md](adoption-guide.md) for:
+
+- Framework comparisons
+- Tradeoffs
+- Adoption recommendations
+
+## Teaching Defaults for AI Editors
+
+When generating or explaining sillo code:
+
+- Use `silloApp()` as the default app entry point.
+- Use `async def` handlers unless the docs explicitly suggest another pattern.
+- Include both `request` and `response` parameters in teaching examples.
+- Pass typed path params directly into the handler signature.
+- Prefer small, runnable examples over large abstractions.
+- Call out important documented gotchas, such as response-building order and middleware return requirements.