Skip to content

Commit 7539cfb

Browse files
n3radan3rada
authored
docs(graphspy): add development guidance, AI policy and refresh uv metadata (#24)
* docs(graphspy): add development guidance and refresh uv metadata * docs(ai): add AI usage policy * docs(ai): slim AI.md, cut DEVELOPMENT.md duplication, fix bullet style * Update DEVELOPMENT.md to refer to AI Policy * Added reference to AI_POLICY.md in readme --------- Co-authored-by: RedByte
1 parent 22a56e6 commit 7539cfb

9 files changed

Lines changed: 551 additions & 164 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# GraphSpy: Copilot Instructions
2+
3+
Shared project AI guidance lives in [AI.md](AI.md).
4+
5+
Apply the conventions and constraints from [AI.md](AI.md) for all suggestions in this repository.
6+
If this file and [AI.md](AI.md) ever conflict, this file takes precedence for Copilot behavior.

‎AGENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# GraphSpy: Agent Instructions (OpenAI)
2+
3+
Shared project AI guidance lives in [AI.md](AI.md).
4+
5+
When working in this repository:
6+
* Treat [AI.md](AI.md) as the canonical source of coding conventions and architecture guidance.
7+
* If this file and [AI.md](AI.md) ever conflict, this file takes precedence for OpenAI agent behavior.

‎AI.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# GraphSpy: AI Engineering Guide
2+
3+
This file is the canonical AI guidance for this repository. For what GraphSpy is and what it does, see [README.md](README.md).
4+
5+
## Runtime and Tooling
6+
7+
* Python baseline is 3.10+ (see [pyproject.toml](pyproject.toml): `requires-python = ">=3.10,<4.0"`).
8+
* Use `uv` for dependency and environment management in this repo.
9+
* GraphSpy is a Flask web application served by Waitress in normal mode and Flask's development server only when `--dev` is explicitly used.
10+
11+
## Read Order
12+
13+
1. [README.md](README.md) — product capabilities, operator workflows, and feature surface.
14+
2. [DEVELOPMENT.md](DEVELOPMENT.md) — architecture, request lifecycle, schema model, and extension guidance (source of truth).
15+
3. [src/graphspy/cli.py](src/graphspy/cli.py) — entry point, app dir resolution, logging, DB bootstrap, server startup.
16+
4. [src/graphspy/app.py](src/graphspy/app.py) — Flask app factory, blueprint registration, error handling.
17+
5. [src/graphspy/db/schema.py](src/graphspy/db/schema.py) and [src/graphspy/db/migrations.py](src/graphspy/db/migrations.py) — SQLite schema and migration model.
18+
6. Representative core/API modules for the feature you are changing.
19+
20+
## Architecture Summary
21+
22+
GraphSpy has four main layers:
23+
24+
1. **CLI/bootstrap** — [src/graphspy/cli.py](src/graphspy/cli.py) handles startup, argument parsing, DB bootstrap, and server launch.
25+
2. **Web/app composition** — [src/graphspy/app.py](src/graphspy/app.py) creates the Flask app and registers API and page blueprints.
26+
3. **API layer** — modules under [src/graphspy/api](src/graphspy/api) stay thin: parse input, delegate to core/DB helpers, return responses.
27+
4. **Core and data layer** — modules under [src/graphspy/core](src/graphspy/core) implement the product workflows (see [README.md](README.md)). [src/graphspy/db](src/graphspy/db) handles SQLite access, schema, and migrations through [src/graphspy/db/connection.py](src/graphspy/db/connection.py).
28+
29+
See [DEVELOPMENT.md](DEVELOPMENT.md) for full design principles, feature boundaries, and request lifecycle details.
30+
31+
## Python Rules
32+
33+
1. **Imports** — standard library, third-party, local. Explicit section comments: `# Built-in imports`, `# Third party library imports`, `# Local library imports`.
34+
2. **Typing** — modern 3.10+ syntax (`X | Y`, `X | None`). Keep return type annotations honest.
35+
3. **Error handling** — avoid broad `except Exception`. Use Loguru throughout. Use `logger.exception(...)` when stack traces matter. Use `AppError` for application-level errors that should flow through Flask handlers.
36+
4. **Code hygiene** — minimal diffs, no style churn in files you touch, comments only where the why is non-obvious.
37+
38+
## Microsoft Documentation
39+
40+
Use Microsoft documentation when behavior depends on service semantics, permissions, or protocol details.
41+
42+
* Microsoft Graph overview: https://learn.microsoft.com/graph/overview
43+
* Microsoft Graph REST API v1.0 reference: https://learn.microsoft.com/graph/api/overview?view=graph-rest-1.0
44+
* Microsoft Graph throttling guidance: https://learn.microsoft.com/graph/throttling
45+
* Microsoft identity platform OAuth 2.0 device authorization grant: https://learn.microsoft.com/entra/identity-platform/v2-oauth2-device-code
46+
* Microsoft Graph authentication and permissions overview: https://learn.microsoft.com/graph/auth/auth-concepts
47+
* Microsoft Graph user resource: https://learn.microsoft.com/graph/api/resources/user?view=graph-rest-1.0
48+
* Microsoft Graph driveItem resource: https://learn.microsoft.com/graph/api/resources/driveitem?view=graph-rest-1.0
49+
* Microsoft Graph site resource: https://learn.microsoft.com/graph/api/resources/site?view=graph-rest-1.0
50+
* Microsoft Graph authentication methods API overview: https://learn.microsoft.com/graph/api/resources/authenticationmethods-overview?view=graph-rest-1.0
51+
* Microsoft Graph teams/conversation resources: https://learn.microsoft.com/graph/api/resources/teams-api-overview?view=graph-rest-1.0
52+
53+
## Testing and Validation
54+
55+
* Validate syntax or startup surface for the slice you changed.
56+
* For dependency changes, keep [pyproject.toml](pyproject.toml) and [uv.lock](uv.lock) synchronized.
57+
* For DB changes, validate both fresh initialization and migration behavior.
58+
* For API changes, prefer a focused request-path or startup validation.
59+
60+
## Definition of Done
61+
62+
A change is complete only if all are true:
63+
64+
1. The change respects the existing CLI/app/API/core/DB layering.
65+
2. Any schema change includes migration handling.
66+
3. Proxy, logging, and error-handling behavior remain intentional.
67+
4. Python 3.10+ compatibility is preserved.
68+
5. Relevant Microsoft API semantics were checked when behavior depends on them.
69+
6. [pyproject.toml](pyproject.toml) and [uv.lock](uv.lock) remain consistent when dependencies change.

‎AI_POLICY.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# AI Usage Policy
2+
3+
GraphSpy has explicit rules for AI-assisted contributions.
4+
5+
1. **Disclose all AI usage.** State the tool(s) used (e.g. Claude Code, Copilot, Cursor) and the extent of AI assistance directly in the pull request description.
6+
2. **Understand everything you submit.** If you cannot explain what your changes do and how they interact with the existing architecture without the aid of AI, do not submit them. Unreviewed AI output is not a contribution.
7+
3. **Review before posting.** Issues and discussions may involve AI assistance, but any content must be reviewed and edited by a human before submission. Strip the noise, keep what is accurate and relevant.
8+
4. **No AI-generated media** (images, diagrams, audio, video, etc.).
9+
5. **Repeated low-effort AI submissions will result in a permanent contribution ban.**
10+
11+
These rules apply to outside contributors. Maintainers are trusted to apply their own judgment.
12+
13+
# AI is Welcome Here
14+
15+
GraphSpy was built entirely by humans. The `AI.md` and `AGENTS.md` files in this repository exist to give AI tools enough context to understand the project so that contributors using those tools do not work against the existing structure.
16+
17+
This policy is not anti-AI. It exists because unreviewed, poorly-directed AI output puts an unfair burden on maintainers. Whether AI-assisted or not, contributors are expected to take full ownership of what they submit.

‎CLAUDE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# GraphSpy: Agent Instructions (Claude)
2+
3+
Shared project AI guidance lives in [AI.md](AI.md).
4+
5+
@AI.md
6+
7+
If this file and [AI.md](AI.md) ever conflict, this file takes precedence for Claude-specific behavior.

0 commit comments

Comments
 (0)