Repository Guidelines

Project Structure & Module Organization

```
src/agent_smb/
```
: Core package (CLI, services, database, middleware).
```
tests/
```
: Pytest suite (markers: unit, integration, auth, slow, asyncio).
```
docs/
```
: Guides and design (see CLI, API, Architecture).
```
scripts/
```
: Docker and operational scripts.
```
serverless_auth/
```
: AWS Lambda authorizer (see details).
```
sql/
```
: Schema and test setup SQL.
```
proxy/local/
```
: Local Nginx config.

Build, Test, and Development Commands

Install (editable):

pip install -r requirements.txt && pip install -e .

Dev setup:
```
pip install -r requirements-dev.txt
```
Run CLI:
```
agent-smb --help
```
(see CLI guide)
Tests (all):
```
pytest -q -v
```
(config:
```
pytest.ini
```
)
Tests (skip slow):
```
pytest -m "not slow"
```

Coverage reports:

pytest --cov=src --cov-report=term-missing

Lint:
```
ruff check .
```
Format:
```
black . && isort .
```
Type check:
```
mypy src
```
(settings:
```
pyproject.toml
```
)
Docker (dev):
```
scripts/docker/dev-up.sh
```
/
```
dev-down.sh
```
(see README)

Coding Style & Naming Conventions

Python 3.8+, 4-space indentation, max line length 88 (Black; see
```
pyproject.toml
```
).
Use type hints;
```
mypy
```
rules in
```
pyproject.toml
```
.
Naming: modules/functions
```
snake_case
```
, classes
```
CamelCase
```
, constants
```
UPPER_SNAKE
```
.
Keep public APIs in
```
src/agent_smb/
```
cohesive; prefer small, testable functions.
Run
```
ruff
```
,
```
black
```
, and
```
isort
```
before pushing (listed in
```
requirements-dev.txt
```
).

Testing Guidelines

Framework: Pytest (see
```
pytest.ini
```
); tests under
```
tests/
```
, files
```
test_*.py
```
, classes
```
Test*
```
, functions
```
test_*
```
.

Use markers:

@pytest.mark.unit

integration

auth

slow

asyncio

Aim for strong coverage; XML/HTML reports enabled (see testing guide).

Example:

pytest tests/test_document_service.py -m unit -q

Commit & Pull Request Guidelines

Commits: imperative mood, concise scope, reference issues (e.g.,
```
feat(cli): add ingest-dir (#123)
```
).
Include tests and docs updates with code changes.
PRs must include: summary, rationale, screenshots/API examples where relevant, passing CI, and linked issues (see auto-PR setup).
Keep PRs focused; note breaking changes in the description.

Security & Configuration Tips

Store secrets in environment variables (
```
GOOGLE_API_KEY
```
,
```
OPENAI_API_KEY
```
,
```
DATABASE_URL
```
, etc.).
Do not commit credentials;
```
pytest
```
loads
```
.env
```
(see
```
pytest.ini
```
).
For local APIs and ports, see README and API guide. For auth, see design.

Architecture & Design Docs

Overview: MVP Design, Resource Hierarchy, Chat History
Data: Documents Storage, Document Metadata
Vector DB: ChromaDB Tradeoffs, Pinecone Migration Plan
Implementation: API Explained, Deployment Explained, MVP Plan, LangGraph Plan
Access Control: Public Agent Access Control

Deployment & Infrastructure

Local: Local Deployment Guide, Docker scripts
```
prod-up.sh
```
/
```
prod-down.sh
```
AWS: AWS Setup, API Gateway Details, Lambda Authorizer

Compose files:

docker-compose.yml

docker-compose.local.yml

docker-compose.prod.yml

Cloud (Alt): DigitalOcean Droplets Setup
Proxy & Networking:
```
proxy/local/nginx.conf
```
, API Gateway CORS Guide

Database & Schema

Schema:
```
sql/schema.sql
```
, tests:
```
sql/test_setup.sql
```
Operations: DB Management, Operational Manual

Agent-Specific Notes

CLI entrypoint:
```
agent-smb
```
(defined in
```
setup.py
```
; implementation in
```
src/agent_smb/cli.py
```
).

Common commands:

agent-smb ingest <file.pdf>

agent-smb ingest-dir <dir>

agent-smb ask "..." --show-sources

(see usage guide).

Repository Guidelines

Project Structure & Module Organization

```
src/agent_smb/
```
: Core package (CLI, services, database, middleware).
```
tests/
```
: Pytest suite (markers: unit, integration, auth, slow, asyncio).
```
docs/
```
: Guides and design (see CLI, API, Architecture).
```
scripts/
```
: Docker and operational scripts.
```
serverless_auth/
```
: AWS Lambda authorizer (see details).
```
sql/
```
: Schema and test setup SQL.
```
proxy/local/
```
: Local Nginx config.

Build, Test, and Development Commands

Install (editable):

pip install -r requirements.txt && pip install -e .

Dev setup:
```
pip install -r requirements-dev.txt
```
Run CLI:
```
agent-smb --help
```
(see CLI guide)
Tests (all):
```
pytest -q -v
```
(config:
```
pytest.ini
```
)
Tests (skip slow):
```
pytest -m "not slow"
```

Coverage reports:

pytest --cov=src --cov-report=term-missing

Lint:
```
ruff check .
```
Format:
```
black . && isort .
```
Type check:
```
mypy src
```
(settings:
```
pyproject.toml
```
)
Docker (dev):
```
scripts/docker/dev-up.sh
```
/
```
dev-down.sh
```
(see README)

Coding Style & Naming Conventions

Python 3.8+, 4-space indentation, max line length 88 (Black; see
```
pyproject.toml
```
).
Use type hints;
```
mypy
```
rules in
```
pyproject.toml
```
.
Naming: modules/functions
```
snake_case
```
, classes
```
CamelCase
```
, constants
```
UPPER_SNAKE
```
.
Keep public APIs in
```
src/agent_smb/
```
cohesive; prefer small, testable functions.
Run
```
ruff
```
,
```
black
```
, and
```
isort
```
before pushing (listed in
```
requirements-dev.txt
```
).

Testing Guidelines

Framework: Pytest (see
```
pytest.ini
```
); tests under
```
tests/
```
, files
```
test_*.py
```
, classes
```
Test*
```
, functions
```
test_*
```
.

Use markers:

@pytest.mark.unit

integration

auth

slow

asyncio

Aim for strong coverage; XML/HTML reports enabled (see testing guide).

Example:

pytest tests/test_document_service.py -m unit -q

Commit & Pull Request Guidelines

Commits: imperative mood, concise scope, reference issues (e.g.,
```
feat(cli): add ingest-dir (#123)
```
).
Include tests and docs updates with code changes.
PRs must include: summary, rationale, screenshots/API examples where relevant, passing CI, and linked issues (see auto-PR setup).
Keep PRs focused; note breaking changes in the description.

Security & Configuration Tips

Store secrets in environment variables (
```
GOOGLE_API_KEY
```
,
```
OPENAI_API_KEY
```
,
```
DATABASE_URL
```
, etc.).
Do not commit credentials;
```
pytest
```
loads
```
.env
```
(see
```
pytest.ini
```
).
For local APIs and ports, see README and API guide. For auth, see design.