103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# LLM Coding Standards (GIA)
|
||
|
||
This document defines implementation standards for coding LLM agents working in this repository.
|
||
|
||
## 1) Repository Context
|
||
|
||
GIA is a multi-transport communication workspace with these major domains:
|
||
|
||
- Transport runtime and relay (`core/modules/router.py`, `core/clients/*`)
|
||
- Shared transport abstraction (`core/clients/transport.py`)
|
||
- Manual compose UX and APIs (`core/views/compose.py` + templates)
|
||
- AI workspace and mitigation operations (`core/views/workspace.py`)
|
||
- OSINT/search UX (`core/views/osint.py`)
|
||
- Core identity/history models (`core/models.py`)
|
||
|
||
The stack is containerized and commonly managed via `make` commands in `Makefile`.
|
||
|
||
## 2) Core Design Principles
|
||
|
||
- Fix root causes first; avoid papering over with UI-only patches.
|
||
- Keep behavior symmetric across `signal`, `whatsapp`, `xmpp`, `instagram` where protocol permits.
|
||
- Centralize shared logic in one place; avoid copy/paste service forks.
|
||
- Prefer small reusable helpers over monolithic in-function branching.
|
||
- Preserve existing UX unless a task explicitly changes interaction behavior.
|
||
|
||
## 3) Runtime / Restart Policy
|
||
|
||
- If runtime code changes (`core/clients/*`, router, relay, transport), restart runtime before validating.
|
||
- Preferred full stack recycle: `make stop && make run`.
|
||
- Single-service restart is acceptable, but if dependency state is improper, use full recycle.
|
||
|
||
## 4) Media Pipeline Rules
|
||
|
||
- Use one shared attachment prep pipeline (`transport` layer) for outbound service sends.
|
||
- Service adapters should only execute provider-specific API calls after shared prep.
|
||
- Preserve MIME type and filename semantics; infer when source metadata is missing.
|
||
- Never inject internal `/compose/media/blob/...` links as relay body text for attachment-only messages.
|
||
- Blob links are fallback for web/history continuity, not preferred transport payloads.
|
||
|
||
## 5) XMPP Upload/Share Rules
|
||
|
||
- Preferred config: `XMPP_UPLOAD_SERVICE` or `XMPP_UPLOAD_JID`.
|
||
- If config absent, use XEP-0363 discovery and normalize discovery to a valid JID.
|
||
- Do not pass raw stanza XML where JID is expected.
|
||
- Keep one place for upload slot and upload error handling semantics.
|
||
|
||
## 6) Transport Symmetry & Performance
|
||
|
||
- Improvements for one service’s media path should be mirrored for others when applicable.
|
||
- Keep performance tuning entry points centralized in shared transport helpers.
|
||
- One TODO location per shared bottleneck (e.g. stream-as-completed optimization), not repeated per service.
|
||
|
||
## 7) Logging and Diagnostics
|
||
|
||
- Keep production logs high signal:
|
||
- lifecycle at info
|
||
- warnings/errors for operational failures
|
||
- high-volume traces at debug
|
||
- Temporary deep diagnostics must be gated (e.g. `WHATSAPP_DEBUG`) and removable in one patch.
|
||
- Avoid ad-hoc/unprofessional debug strings.
|
||
|
||
## 8) Large File Refactoring Policy
|
||
|
||
When touching large files (especially ~2000+ lines):
|
||
|
||
- Extract minimal reusable helpers in-place or to shared modules.
|
||
- Add short docstrings for shared utility functions.
|
||
- Avoid introducing new repeated service-specific branches.
|
||
|
||
## 9) Documentation Maintenance Standards
|
||
|
||
Maintain docs as follows:
|
||
|
||
- `INSTALL.md` owns setup/config/restart/troubleshooting.
|
||
- `README.md` owns capability map, operation modes, architecture, and interface workflows.
|
||
- Keep README setup instructions short and point to INSTALL first.
|
||
- Update both docs when operational commands/env requirements change.
|
||
- Reflect significant behavior changes (relay semantics, media fallback rules, runtime handoff) in docs immediately.
|
||
|
||
## 10) Validation Workflow
|
||
|
||
- Run targeted checks for changed files.
|
||
- Validate runtime behavior with real channel tests after restart.
|
||
- For media/relay changes, validate both directions:
|
||
- XMPP -> service
|
||
- service -> XMPP
|
||
- Confirm no regression in web compose display semantics.
|
||
|
||
## 11) Security & TLS Operational Baseline
|
||
|
||
- Keep upload endpoints compatible and modern (`TLSv1.2` + `TLSv1.3`).
|
||
- Maintain valid certificate chain/stapling where configured.
|
||
- Treat TLS/protocol mismatch as infra blocker before application-layer debugging.
|
||
|
||
## 12) Current Operational Priorities (Living Guidance)
|
||
|
||
As of current project state:
|
||
|
||
- Stabilize live WhatsApp<->XMPP sync behavior.
|
||
- Complete media relay parity and offline/backfill consistency.
|
||
- Continue reducing transport-specific duplication through shared abstractions.
|
||
- Keep compose and workspace indicators clear and non-ambiguous.
|