Fix linting and additional doc details

Author: nirvanatikku

CHANGELOG.md

@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`IntentLease.from_dict()` KeyError on server responses** — `acquire_lease()` threw `KeyError('status')` because the server's `LeaseResponse` model does not include a `status` field (it uses `acquired_at`, `expires_at`, and `released_at` to represent lease state). `IntentLease.from_dict()` now derives status from these fields: `RELEASED` if `released_at` is set, `EXPIRED` if `expires_at` is in the past, otherwise `ACTIVE`. Also handles the field name difference `acquired_at` (server) vs `created_at` (SDK). Backward compatible with the SDK's own serialization format.
 
+- **Stale database singleton after server restart** — `get_database()` cached the `Database` instance at module level and never checked whether `database_url` changed between calls. When the protocol server restarted on a different port (e.g., `openintent_server_8001.db` → `openintent_server_8002.db`), the singleton kept pointing at the old file. Writes went to the old database; reads came from the new (empty) one — intents appeared created but were invisible to `list_intents`. The singleton now tracks its URL and recreates the connection when the URL changes.
+
 - **Example and test updates** — All examples (`basic_usage.py`, `openai_multi_agent.py`, `multi_agent/coordinator.py`, `compliance_review/coordinator.py`) and tests updated to use dict-format constraints.
 
 ### Changed

CONTRIBUTING.md

@@ -25,14 +25,21 @@ Thank you for your interest in contributing to the OpenIntent Python SDK! This d
 
 We use the following tools for code quality:
 
-- **Black** for code formatting
-- **Ruff** for linting
+- **Ruff** for linting and code formatting
 - **mypy** for type checking
+- **pre-commit** for automatic formatting on every commit
+
+Set up pre-commit hooks (runs automatically with `make install-dev`):
+
+```bash
+pip install pre-commit
+pre-commit install
+```
 
 Before submitting a PR, run:
 
 ```bash
-black openintent/
+ruff format openintent/
 ruff check openintent/ --fix
 mypy openintent/
 ```

Makefile

@@ -8,89 +8,90 @@ PORT ?= 8000
 MCP_ROLE ?= reader
 
 help: ## Show this help message
-        @echo "OpenIntent SDK — available targets:"
-        @echo ""
-        @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
-                awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
-        @echo ""
-        @echo "Variables (override with VAR=value):"
-        @echo "  PORT          Server port         (default: $(PORT))"
-        @echo "  MCP_ROLE      MCP server role      (default: $(MCP_ROLE))"
-        @echo "  PYTHON        Python binary        (default: $(PYTHON))"
+	@echo "OpenIntent SDK — available targets:"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
+	@echo ""
+	@echo "Variables (override with VAR=value):"
+	@echo "  PORT          Server port         (default: $(PORT))"
+	@echo "  MCP_ROLE      MCP server role      (default: $(MCP_ROLE))"
+	@echo "  PYTHON        Python binary        (default: $(PYTHON))"
 
 install: ## Install SDK with server + all adapters
-        $(PIP) install -e ".[server,all-adapters]"
+	$(PIP) install -e ".[server,all-adapters]"
 
 install-dev: ## Install SDK with dev + server + all extras
-        $(PIP) install -e ".[dev,server,all-adapters]"
+	$(PIP) install -e ".[dev,server,all-adapters]"
+	@if command -v pre-commit >/dev/null 2>&1; then pre-commit install; fi
 
 install-all: ## Install everything including MCP dependencies
-        $(PIP) install -e ".[dev,server,all-adapters]"
-        $(PIP) install mcp
-        npm install -g @openintentai/mcp-server
+	$(PIP) install -e ".[dev,server,all-adapters]"
+	$(PIP) install mcp
+	npm install -g @openintentai/mcp-server
 
 server: ## Start the OpenIntent server
-        openintent-server --port $(PORT)
+	openintent-server --port $(PORT)
 
 test: ## Run the full test suite
-        $(PYTHON) -m pytest tests/ -v
+	$(PYTHON) -m pytest tests/ -v
 
 test-quick: ## Run tests without slow markers
-        $(PYTHON) -m pytest tests/ -v -m "not slow"
+	$(PYTHON) -m pytest tests/ -v -m "not slow"
 
 test-mcp: ## Run MCP-related tests only
-        $(PYTHON) -m pytest tests/ -v -k "mcp"
+	$(PYTHON) -m pytest tests/ -v -k "mcp"
 
 lint: ## Run linter + formatter check + type checker
-        ruff check openintent/
-        black --check openintent/
-        mypy openintent/
+	ruff check openintent/
+	ruff format --check openintent/
+	mypy openintent/
 
 format: ## Auto-format code
-        black openintent/ tests/
-        ruff check --fix openintent/
+	ruff format openintent/ tests/ examples/
+	ruff check --fix openintent/
 
 typecheck: ## Run type checker only
-        mypy openintent/
+	mypy openintent/
 
 setup-mcp: ## Install MCP dependencies (Python + Node)
-        @echo "Installing Python MCP SDK..."
-        $(PIP) install mcp
-        @echo "Installing OpenIntent MCP server (Node)..."
-        npm install -g @openintentai/mcp-server
-        @echo ""
-        @echo "MCP setup complete. Next steps:"
-        @echo "  make server      — Start the OpenIntent server"
-        @echo "  make mcp-server  — Start the MCP server (in another terminal)"
-        @echo "  make full-stack  — Start both together"
+	@echo "Installing Python MCP SDK..."
+	$(PIP) install mcp
+	@echo "Installing OpenIntent MCP server (Node)..."
+	npm install -g @openintentai/mcp-server
+	@echo ""
+	@echo "MCP setup complete. Next steps:"
+	@echo "  make server      — Start the OpenIntent server"
+	@echo "  make mcp-server  — Start the MCP server (in another terminal)"
+	@echo "  make full-stack  — Start both together"
 
 mcp-server: ## Start the MCP server (connects to local OpenIntent server)
-        OPENINTENT_SERVER_URL=http://localhost:$(PORT) \
-        OPENINTENT_API_KEY=dev-user-key \
-        OPENINTENT_MCP_ROLE=$(MCP_ROLE) \
-        $(NPX) -y @openintentai/mcp-server
+	OPENINTENT_SERVER_URL=http://localhost:$(PORT) \
+	OPENINTENT_API_KEY=dev-user-key \
+	OPENINTENT_MCP_ROLE=$(MCP_ROLE) \
+	$(NPX) -y @openintentai/mcp-server
 
 full-stack: ## Start OpenIntent server + MCP server together
-        @echo "Starting OpenIntent server on port $(PORT)..."
-        @openintent-server --port $(PORT) &
-        @sleep 2
-        @echo "Starting MCP server (role: $(MCP_ROLE))..."
-        @OPENINTENT_SERVER_URL=http://localhost:$(PORT) \
-         OPENINTENT_API_KEY=dev-user-key \
-         OPENINTENT_MCP_ROLE=$(MCP_ROLE) \
-         $(NPX) -y @openintentai/mcp-server
+	@echo "Starting OpenIntent server on port $(PORT)..."
+	@openintent-server --port $(PORT) &
+	@sleep 2
+	@echo "Starting MCP server (role: $(MCP_ROLE))..."
+	@OPENINTENT_SERVER_URL=http://localhost:$(PORT) \
+	 OPENINTENT_API_KEY=dev-user-key \
+	 OPENINTENT_MCP_ROLE=$(MCP_ROLE) \
+	 $(NPX) -y @openintentai/mcp-server
 
 check: ## Verify installation and connectivity
-        @echo "Checking Python SDK..."
-        @$(PYTHON) -c "import openintent; print(f'  openintent {openintent.__version__}')" 2>/dev/null || echo "  openintent: NOT INSTALLED"
-        @echo "Checking MCP SDK..."
-        @$(PYTHON) -c "import mcp; print('  mcp: OK')" 2>/dev/null || echo "  mcp: NOT INSTALLED (run: make setup-mcp)"
-        @echo "Checking MCP server (Node)..."
-        @$(NPX) -y @openintentai/mcp-server --version 2>/dev/null && echo "  mcp-server: OK" || echo "  mcp-server: NOT INSTALLED (run: make setup-mcp)"
-        @echo "Checking OpenIntent server..."
-        @curl -sf http://localhost:$(PORT)/api/v1/intents > /dev/null 2>&1 && echo "  server: RUNNING on port $(PORT)" || echo "  server: NOT RUNNING (run: make server)"
+	@echo "Checking Python SDK..."
+	@$(PYTHON) -c "import openintent; print(f'  openintent {openintent.__version__}')" 2>/dev/null || echo "  openintent: NOT INSTALLED"
+	@echo "Checking MCP SDK..."
+	@$(PYTHON) -c "import mcp; print('  mcp: OK')" 2>/dev/null || echo "  mcp: NOT INSTALLED (run: make setup-mcp)"
+	@echo "Checking MCP server (Node)..."
+	@$(NPX) -y @openintentai/mcp-server --version 2>/dev/null && echo "  mcp-server: OK" || echo "  mcp-server: NOT INSTALLED (run: make setup-mcp)"
+	@echo "Checking OpenIntent server..."
+	@curl -sf http://localhost:$(PORT)/api/v1/intents > /dev/null 2>&1 && echo "  server: RUNNING on port $(PORT)" || echo "  server: NOT RUNNING (run: make server)"
 
 clean: ## Remove build artifacts and caches
-        rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache
-        find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
-        find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true

README.md

@@ -714,7 +714,7 @@ pip install -e ".[dev,server]"
 
 pytest                  # Run tests
 ruff check openintent/  # Lint
-black openintent/       # Format
+ruff format openintent/ # Format
 mypy openintent/        # Type check
 openintent-server       # Start dev server
 ```

docs/changelog.md

@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`IntentLease.from_dict()` KeyError on server responses** — `acquire_lease()` threw `KeyError('status')` because the server's `LeaseResponse` model does not include a `status` field (it uses `acquired_at`, `expires_at`, and `released_at` to represent lease state). `IntentLease.from_dict()` now derives status from these fields: `RELEASED` if `released_at` is set, `EXPIRED` if `expires_at` is in the past, otherwise `ACTIVE`. Also handles the field name difference `acquired_at` (server) vs `created_at` (SDK). Backward compatible with the SDK's own serialization format.
 
+- **Stale database singleton after server restart** — `get_database()` cached the `Database` instance at module level and never checked whether `database_url` changed between calls. When the protocol server restarted on a different port (e.g., `openintent_server_8001.db` → `openintent_server_8002.db`), the singleton kept pointing at the old file. Writes went to the old database; reads came from the new (empty) one — intents appeared created but were invisible to `list_intents`. The singleton now tracks its URL and recreates the connection when the URL changes.
+
 - **Example and test updates** — All examples (`basic_usage.py`, `openai_multi_agent.py`, `multi_agent/coordinator.py`, `compliance_review/coordinator.py`) and tests updated to use dict-format constraints.
 
 ### Changed

examples/multi_agent/coordinator.py

@@ -60,7 +60,9 @@ async def plan(self, topic: str) -> PortfolioSpec:
                     title="Research Phase",
                     description=f"Research the topic: {topic}",
                     assign="research-agent",
-                    constraints={"rules": ["max_cost_usd:0.50", "required_confidence:0.75"]},
+                    constraints={
+                        "rules": ["max_cost_usd:0.50", "required_confidence:0.75"]
+                    },
                     initial_state={"phase": "research"},
                 ),
                 # Phase 2: Writing (depends on Research)

openintent/adapters/gemini_adapter.py

@@ -127,7 +127,9 @@ def generate_content(
         messages_count = (
             1
             if isinstance(contents, str)
-            else len(contents) if isinstance(contents, list) else 1
+            else len(contents)
+            if isinstance(contents, list)
+            else 1
         )
 
         if self._config.log_requests:

openintent/client.py

@@ -3018,7 +3018,9 @@ def list_federated_agents(
             headers=headers,
         )
         data = self._handle_response(response)
-        agents: list[dict[str, Any]] = data if isinstance(data, list) else data.get("agents", [])
+        agents: list[dict[str, Any]] = (
+            data if isinstance(data, list) else data.get("agents", [])
+        )
         return agents
 
     def federation_dispatch(
@@ -5099,7 +5101,9 @@ async def list_federated_agents(
             headers=headers,
         )
         data = self._handle_response(response)
-        agents: list[dict[str, Any]] = data if isinstance(data, list) else data.get("agents", [])
+        agents: list[dict[str, Any]] = (
+            data if isinstance(data, list) else data.get("agents", [])
+        )
         return agents
 
     async def federation_dispatch(

openintent/demo_agents.py

@@ -153,7 +153,9 @@ async def handle_intent(self, intent: Any) -> dict[str, Any]:
             rules = raw_constraints.get("rules", [])
             constraints = "\n".join(str(r) for r in rules) if rules else ""
         else:
-            constraints = "\n".join(str(c) for c in raw_constraints) if raw_constraints else ""
+            constraints = (
+                "\n".join(str(c) for c in raw_constraints) if raw_constraints else ""
+            )
 
         prompt = f"Research the following topic:\n\n{topic}"
         if constraints:

openintent/models.py

@@ -932,14 +932,20 @@ def from_dict(cls, data: dict[str, Any]) -> "IntentLease":
             if expires_str:
                 try:
                     expires = datetime.fromisoformat(expires_str)
-                    status = LeaseStatus.ACTIVE if datetime.now(expires.tzinfo) < expires else LeaseStatus.EXPIRED
+                    status = (
+                        LeaseStatus.ACTIVE
+                        if datetime.now(expires.tzinfo) < expires
+                        else LeaseStatus.EXPIRED
+                    )
                 except (ValueError, TypeError):
                     status = LeaseStatus.ACTIVE
             else:
                 status = LeaseStatus.ACTIVE
 
         created_at_str = data.get("created_at") or data.get("acquired_at")
-        created_at = datetime.fromisoformat(created_at_str) if created_at_str else datetime.now()
+        created_at = (
+            datetime.fromisoformat(created_at_str) if created_at_str else datetime.now()
+        )
 
         return cls(
             id=data["id"],