Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(knowledge_writer): register the knowledge writer product skeleton (#128420)

John C. Waters52430764b679
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 37bc3d543504..b662e3ba92ad 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4098,6 +4098,8 @@ importers:
specifier: 'catalog:'
version: 0.2.4([email protected](patch_hash=139b8d1f1304f9d9da452a9a1244c94ea679dbcb85687d8999563146879fb6f5)([email protected]))
+ products/knowledge_writer: {}
+
products/legal_documents:
dependencies:
'@posthog/icons':
diff --git a/posthog/settings/web.py b/posthog/settings/web.py
index 2f7686dcbf7a..bc018c6300ec 100644
--- a/posthog/settings/web.py
+++ b/posthog/settings/web.py
@@ -52,6 +52,7 @@ PRODUCTS_APPS = [
"products.tasks.backend.apps.TasksConfig",
"products.canvas.backend.apps.CanvasConfig",
"products.stamphog.backend.apps.StamphogConfig",
+ "products.knowledge_writer.backend.apps.KnowledgeWriterConfig",
"products.today.backend.apps.TodayConfig",
"products.links.backend.apps.LinksConfig",
"products.field_notes.backend.apps.FieldNotesConfig",
diff --git a/products/knowledge_writer/__init__.py b/products/knowledge_writer/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/knowledge_writer/backend/__init__.py b/products/knowledge_writer/backend/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/knowledge_writer/backend/apps.py b/products/knowledge_writer/backend/apps.py
new file mode 100644
index 000000000000..f310a9126047
--- /dev/null
+++ b/products/knowledge_writer/backend/apps.py
@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class KnowledgeWriterConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "products.knowledge_writer.backend"
+ label = "knowledge_writer"
diff --git a/products/knowledge_writer/backend/facade/__init__.py b/products/knowledge_writer/backend/facade/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/knowledge_writer/backend/facade/api.py b/products/knowledge_writer/backend/facade/api.py
new file mode 100644
index 000000000000..882c430ba021
--- /dev/null
+++ b/products/knowledge_writer/backend/facade/api.py
@@ -0,0 +1,6 @@
+from ..settings import writer_settings
+
+
+def writer_team_id() -> int | None:
+ writer = writer_settings()
+ return writer.team_id if writer else None
diff --git a/products/knowledge_writer/backend/facade/contracts.py b/products/knowledge_writer/backend/facade/contracts.py
new file mode 100644
index 000000000000..6fbb8f8dd40d
--- /dev/null
+++ b/products/knowledge_writer/backend/facade/contracts.py
@@ -0,0 +1,76 @@
+from typing import Annotated, ClassVar, Literal, Protocol, TypeVar
+from uuid import UUID
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from .enums import DocsChangeKind, DocsRequestSource
+
+RawEvent = TypeVar("RawEvent", contravariant=True)
+
+TASK_ORIGIN_KEY_MAX_LENGTH = 128
+
+DedupeId = Annotated[
+ str, Field(pattern=r"^knowledge_writer:[a-z_]+:[A-Za-z0-9._#-]+$", max_length=TASK_ORIGIN_KEY_MAX_LENGTH)
+]
+
+
+@dataclass(frozen=True, config={"extra": "forbid"})
+class DocsRequest:
+ source: DocsRequestSource
+ source_url: str
+ evidence: str
+ change_kind: DocsChangeKind
+ suggested_page_urls: Annotated[tuple[str, ...], Field(max_length=3)]
+ trigger_instructions: str
+ dedupe_id: DedupeId
+ requested_by: str | None = None
+ requested_by_user_id: int | None = None
+ skip_judge: bool = False
+
+
+@dataclass(frozen=True, config={"extra": "forbid"})
+class AdapterVerdict:
+ source: DocsRequestSource
+ subject_id: str
+ needs_docs: bool
+ reason: str
+ request: DocsRequest | None
+
+ def __post_init__(self) -> None:
+ if self.needs_docs != (self.request is not None):
+ raise ValueError("request is set exactly when needs_docs")
+ if self.request is not None and self.request.source != self.source:
+ raise ValueError("request.source must match verdict.source")
+
+
+class Adapter(Protocol[RawEvent]):
+ source: ClassVar[DocsRequestSource]
+ instructions: ClassVar[str]
+
+ def assess(self, event: RawEvent) -> AdapterVerdict: ...
+
+
+@dataclass(frozen=True, config={"extra": "forbid"})
+class DocsCommandRequest:
+ repository: str
+ pull_request_number: int
+ pull_request_url: str
+ head_sha: str
+ note: str
+ requested_by: str
+ requested_by_user_id: int
+
+
+IntakeStatus = Literal["no_docs", "unconfigured", "duplicate", "capped", "shadow", "joined", "started"]
+
+
+@dataclass(frozen=True)
+class IntakeOutcome:
+ status: IntakeStatus
+ task_id: UUID | None = None
+ pull_request_url: str | None = None
+
+
+class InvalidAdapterVerdict(ValueError):
+ pass
diff --git a/products/knowledge_writer/backend/facade/enums.py b/products/knowledge_writer/backend/facade/enums.py
new file mode 100644
index 000000000000..33b2318e3136
--- /dev/null
+++ b/products/knowledge_writer/backend/facade/enums.py
@@ -0,0 +1,12 @@
+from enum import StrEnum
+
+
+class DocsRequestSource(StrEnum):
+ REPO_MERGE = "repo_merge"
+ COMMAND_TAG = "command_tag"
+
+
+class DocsChangeKind(StrEnum):
+ UPDATE = "update"
+ CREATE = "create"
+ REMOVE = "remove"
diff --git a/products/knowledge_writer/backend/feature_flags.py b/products/knowledge_writer/backend/feature_flags.py
new file mode 100644
index 000000000000..24428e87d965
--- /dev/null
+++ b/products/knowledge_writer/backend/feature_flags.py
@@ -0,0 +1,36 @@
+import structlog
+import posthoganalytics
+
+from posthog.models.team import Team
+
+logger = structlog.get_logger(__name__)
+
+WRITER_FLAG = "knowledge-writer"
+AGENT_LAUNCH_FLAG = "knowledge-writer-agent-launch"
+
+
+def is_writer_enabled(team_id: int) -> bool:
+ team = Team.objects.filter(id=team_id).first()
+ if team is None:
+ return False
+ return is_team_flag_enabled(WRITER_FLAG, team)
+
+
+def is_agent_launch_enabled(team: Team) -> bool:
+ return is_team_flag_enabled(AGENT_LAUNCH_FLAG, team)
+
+
+def is_team_flag_enabled(flag: str, team: Team) -> bool:
+ try:
+ return bool(
+ posthoganalytics.feature_enabled(
+ flag,
+ str(team.uuid),
+ groups={"organization": str(team.organization_id)},
+ only_evaluate_locally=False,
+ send_feature_flag_events=False,
+ )
+ )
+ except Exception:
+ logger.exception("knowledge_writer_flag_check_failed", team_id=team.id, flag=flag)
+ return False
diff --git a/products/knowledge_writer/backend/settings.py b/products/knowledge_writer/backend/settings.py
new file mode 100644
index 000000000000..dfdea020e043
--- /dev/null
+++ b/products/knowledge_writer/backend/settings.py
@@ -0,0 +1,22 @@
+from posthog.dataclasses import frozen
+from posthog.settings.utils import get_from_env
+
+from .feature_flags import is_writer_enabled
+
+
+@frozen
+class WriterSettings:
+ team_id: int
+ user_id: int
+ docs_repository: str
+
+
+def writer_settings() -> WriterSettings | None:
+ team_id = get_from_env("KNOWLEDGE_WRITER_TEAM_ID", optional=True, type_cast=int)
+ user_id = get_from_env("KNOWLEDGE_WRITER_USER_ID", optional=True, type_cast=int)
+ docs_repository = get_from_env("KNOWLEDGE_WRITER_DOCS_REPOSITORY", optional=True)
+ if team_id is None or user_id is None or not docs_repository:
+ return None
+ if not is_writer_enabled(team_id):
+ return None
+ return WriterSettings(team_id=team_id, user_id=user_id, docs_repository=docs_repository)
diff --git a/products/knowledge_writer/backend/tests/__init__.py b/products/knowledge_writer/backend/tests/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/knowledge_writer/manifest.tsx b/products/knowledge_writer/manifest.tsx
new file mode 100644
index 000000000000..8e74a077f4a2
--- /dev/null
+++ b/products/knowledge_writer/manifest.tsx
@@ -0,0 +1,12 @@
+import { ProductManifest } from '../../frontend/src/types'
+
+export const manifest: ProductManifest = {
+ name: 'KnowledgeWriter',
+ scenes: {},
+ routes: {},
+ redirects: {},
+ urls: {},
+ fileSystemTypes: {},
+ treeItemsNew: [],
+ treeItemsProducts: [],
+}
diff --git a/products/knowledge_writer/package.json b/products/knowledge_writer/package.json
new file mode 100644
index 000000000000..55d32d3e3e4d
--- /dev/null
+++ b/products/knowledge_writer/package.json
@@ -0,0 +1,7 @@
+{
+ "name": "@posthog/products-knowledge-writer",
+ "scripts": {
+ "backend:test": "pytest -c ../../pytest.ini --rootdir ../.. backend/tests -v --tb=short",
+ "backend:contract-check": "echo 'Contract files unchanged'"
+ }
+}
diff --git a/products/knowledge_writer/product.yaml b/products/knowledge_writer/product.yaml
new file mode 100644
index 000000000000..47443d3fbcae
--- /dev/null
+++ b/products/knowledge_writer/product.yaml
@@ -0,0 +1,3 @@
+name: Knowledge writer
+owners:
+ - team-wizard-docs
diff --git a/products/knowledge_writer/tsconfig.json b/products/knowledge_writer/tsconfig.json
new file mode 100644
index 000000000000..fe425d6fcba8
--- /dev/null
+++ b/products/knowledge_writer/tsconfig.json
@@ -0,0 +1,6 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "composite": true
+ }
+}
diff --git a/products/knowledge_writer/turbo.json b/products/knowledge_writer/turbo.json
new file mode 100644
index 000000000000..51fc5e97a7b0
--- /dev/null
+++ b/products/knowledge_writer/turbo.json
@@ -0,0 +1,15 @@
+{
+ "extends": ["//"],
+ "tasks": {
+ "backend:contract-check": {
+ "inputs": [
+ "backend/facade/**",
+ "backend/webhook_consumers.py",
+ "backend/tasks/**",
+ "backend/migrations/**"
+ ],
+ "outputs": [],
+ "cache": true
+ }
+ }
+}
diff --git a/tach.toml b/tach.toml
index bf4864c17bb4..6bc6853f9894 100644
--- a/tach.toml
+++ b/tach.toml
@@ -2000,3 +2000,16 @@ expose = [
from = [
"products.authorization",
]
+
+[[modules]]
+path = "products.knowledge_writer"
+depends_on = ["posthog", "products.tasks"]
+layer = "modules"
+
+[[interfaces]]
+expose = [
+ "backend\\.facade.*",
+]
+from = [
+ "products.knowledge_writer",
+]