classifyre-cli 0.4.2__py3-none-any.whl

classifyre_cli-0.4.2.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: classifyre-cli
+Version: 0.4.2
+Summary: Classifyre CLI — scan and classify unstructured data sources
+License: MIT
+Keywords: data,ingestion,metadata,pii,secrets,unstructured
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: classifyre-schemas
+Requires-Dist: email-validator>=2.3.0
+Requires-Dist: en-core-web-sm
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: lxml>=6.1.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: requests>=2.34.2
+Description-Content-Type: text/markdown
+
+# CLI Application
+
+Python CLI for source extraction, detector execution, and batched output delivery.
+
+## Setup
+
+```bash
+cd /unstructured/apps/cli
+uv sync
+# Optional if you want an activated shell instead of `uv run ...`:
+source .venv/bin/activate
+```
+
+Optional detector groups:
+
+```bash
+uv sync --group detectors
+# or specific groups: --group secrets --group pii --group threat ...
+```
+
+## Command Syntax
+
+Use the thin wrapper:
+
+```bash
+uv run main.py <command> <recipe.json> [options]
+```
+
+Or direct module entrypoint:
+
+```bash
+uv run python -m src.main <command> <recipe.json> [options]
+```
+
+Commands:
+
+- `test` - test source connection.
+- `discover` - discover source resources.
+- `extract` - run extraction and emit batched output.
+- `sandbox` - run sandbox parsing/detectors for a local file.
+
+## Extract Output Model
+
+Extraction always emits in batches.
+Recipes do not contain `output` configuration; output is controlled by CLI flags and environment variables.
+
+Output types:
+
+- `console` - emits NDJSON envelopes to stdout.
+- `file` - appends NDJSON envelopes to a file.
+- `rest` - pushes batches to API endpoints and finalizes run.
+
+Default behavior:
+
+- If `source_id` is present (`--source-id` or `SOURCE_ID` env), default output is `rest`.
+- Otherwise default output is `console`.
+- Default batch size is `20`.
+
+## CLI Options
+
+Global/common:
+
+- `--debug` - enable debug logging.
+- `--detectors-file <path>` - sandbox only.
+
+Extract output options:
+
+- `--output-type rest|file|console`
+- `--output-batch-size <int>`
+- `--output-rest-url <url>`
+- `--output-file-path <path>`
+- `--source-id <uuid>`
+- `--runner-id <uuid>`
+- `--managed-runner` (REST only; runner lifecycle managed by API orchestrator)
+
+Environment fallbacks:
+
+- `SOURCE_ID`, `RUNNER_ID`
+- `CLASSIFYRE_OUTPUT_TYPE`, `CLASSIFYRE_OUTPUT_BATCH_SIZE`
+- `CLASSIFYRE_OUTPUT_REST_URL`, `CLASSIFYRE_OUTPUT_REST_TIMEOUT_SEC`
+- `CLASSIFYRE_OUTPUT_FILE_PATH`
+- `API_URL` (fallback base URL for REST output)
+
+## Practical Examples
+
+### 1) Console output (quick local test)
+
+```bash
+uv run main.py extract ./wordpress-recipe.json --output-type console --output-batch-size 1
+```
+
+You will see NDJSON lines like:
+
+- `{"event":"batch", ...}`
+- `{"event":"finish", ...}`
+
+### 2) File output
+
+```bash
+uv run main.py extract ./wordpress-recipe.json \
+  --output-type file \
+  --output-file-path /tmp/classifyre-assets.ndjson \
+  --output-batch-size 20
+```
+
+### 3) REST output (manual CLI to backend)
+
+```bash
+uv run main.py extract ./wordpress-recipe.json \
+  --output-type rest \
+  --source-id <source_uuid>
+```
+
+Notes:
+
+- `--runner-id` optional for manual runs. If omitted, CLI creates external runner automatically.
+- `--output-rest-url` is optional. If omitted, CLI uses `CLASSIFYRE_OUTPUT_REST_URL`, then `API_URL`, then `http://localhost:8000`.
+- `--managed-runner` should be used only for API-orchestrated runs where runner already exists.
+
+### 4) REST output with explicit runner (managed/orchestrated style)
+
+```bash
+uv run main.py extract ./wordpress-recipe.json \
+  --output-type rest \
+  --source-id <source_uuid> \
+  --runner-id <runner_uuid> \
+  --managed-runner
+```
+
+### 5) Full extract command with all output flags
+
+```bash
+uv run main.py extract ./wordpress-recipe.json \
+  --output-type rest \
+  --output-batch-size 20 \
+  --output-rest-url http://localhost:8000 \
+  --output-file-path /tmp/classifyre-assets.ndjson \
+  --source-id <source_uuid> \
+  --runner-id <runner_uuid> \
+  --managed-runner
+```
+
+Use `--output-file-path` only when `--output-type file`.
+
+## Dev Scripts
+
+- `bun run dev` - run CLI quickly.
+- `bun run lint` - ruff format/check.
+- `bun run check-types` - mypy.
+- `bun run test` - pytest suite.

classifyre_cli-0.4.2.dist-info/RECORD

@@ -0,0 +1,101 @@
+src/__init__.py,sha256=a9znVQMuKTEdH6nB8kUs7jMmPV1U6IFXDzCU5RnzxFo,23
+src/main.py,sha256=L82WFjaZk7QsXHUNyoOFyxAvHUUSyfP9978kAjgWPUA,24046
+src/telemetry.py,sha256=fbSmuJ_t-kSthfIh3E7ESVkloH22kzl8lQKY370YtuU,3089
+src/detectors/__init__.py,sha256=BWrUF_GtSsfs1nQMvG9UhOpUokqwJ0-5Dyg498VMs4E,3475
+src/detectors/base.py,sha256=bXcPmc_rZG5ONWm_ZgGLT-QpLqK8zXsdAUsguMb3FMg,2998
+src/detectors/config.py,sha256=CCrzp8Js8tQ1E34_Pl9ChY8JFjvUalXbnJJ-QWk54d4,1683
+src/detectors/dependencies.py,sha256=C5FBnkBMWCnx34WkOrM7yTO8zcOV_zP0RbyvMtw8A20,3851
+src/detectors/broken_links/__init__.py,sha256=maN50pAfC9IJGNUUIHGVM4YnjTAozRI43APLUCQrJcE,77
+src/detectors/broken_links/detector.py,sha256=tyFpevrE21PZLj1GHGjlmnGq3c7Lc1OSvYcrSDkpMv8,9330
+src/detectors/content/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/detectors/custom/__init__.py,sha256=HfTzYuQFd7XJbIAhWndqScxbbL0AS7vaOc7p3dkFW6U,296
+src/detectors/custom/detector.py,sha256=SiDyoaRdd7W6JHnI_aGN_U0paF2Q_wenhxPiq-WoxNk,1653
+src/detectors/custom/trainer.py,sha256=xS-eg8Ic6qr_rtMvSlrePFVwrzt9hwC56awSw6gTLOM,11358
+src/detectors/custom/runners/__init__.py,sha256=KWSni4-O2SVfODFhRXWvml_PSg58lShHiBkaEhH8D5Y,1663
+src/detectors/custom/runners/_base.py,sha256=VhQ2fQgJSqsrjj93aDv4_Zw-_kho6TA-pJivewGHnbk,5790
+src/detectors/custom/runners/_factory.py,sha256=Q60Nw2vK6GX5VrrDqwmJllEar10XTgh9BgRUv4GcWi0,2093
+src/detectors/custom/runners/_feature_extraction.py,sha256=U2-EWGR52hqMiLJ10R7Gx72D3MZXNad1w_TEbPJoRo8,5577
+src/detectors/custom/runners/_gliner2.py,sha256=WpEpWHrIFoPkL4WGQ7XWzHekHQ6VWQsmw3Bqm_WFrWU,12680
+src/detectors/custom/runners/_image_classification.py,sha256=43DHRwyA2hXv7UAiXVOzUGzuT8M5IGTE6T9WVuO90Ng,4000
+src/detectors/custom/runners/_llm.py,sha256=viqeuuT_5eC5pqTXXkzhSy1zJyLAj5lzjzHBvg8PONw,731
+src/detectors/custom/runners/_object_detection.py,sha256=C9kfeRbf9GTXu33l8ieQdn4EiGYRWbeRsy0Vq6V4MJQ,4683
+src/detectors/custom/runners/_regex.py,sha256=lq9YA9v12iUXVoqgWWq0dHiPltbnfCBGW9fvYYiAugg,5219
+src/detectors/custom/runners/_text_classification.py,sha256=HhXvXyWAevAn29f8rfneH7GuGFDgmrYHGOe9nf-Bpic,4633
+src/detectors/pii/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/detectors/pii/detector.py,sha256=mLGBom6tLmeTW9ARKb0LDeeyz17-j98UPlBZnX02CH4,33060
+src/detectors/secrets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/detectors/secrets/detector.py,sha256=aq8s0shOj7_fK9YcturY_OX8W8IAcZfg9Von3G1VFcw,13895
+src/detectors/threat/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/detectors/threat/code_security_detector.py,sha256=iUWvHZLwVmhRM_WrOBgG1A_mIsdkNHv5KqcCb5Ap0JU,6900
+src/detectors/threat/yara_detector.py,sha256=ZmxdiDnSIUgSAj0EhVUlRdlcwl4VjOM1CQTIc_fObNE,6275
+src/models/generated_detectors.py,sha256=BfDMufATPOj5-d2AzUxdjLoxUN-IDVMTe6EwOUExoTg,42847
+src/models/generated_input.py,sha256=LeJovpInCNnW0pyliCYUjk947qc6nDgjknsT0QoyA6k,82805
+src/models/generated_single_asset_scan_results.py,sha256=ou4pyGt_Cqg9to_8drCuS_IaE0qGDWJKUHUSIFhZq4E,7269
+src/outputs/__init__.py,sha256=41SESY2nC1y4zF0CTWn1dnTh9AK7qMdRxmRSN_GuWss,126
+src/outputs/base.py,sha256=mRFTwqkaWLqyS55OkdbO49yBnSHXlaIGd_bzLyNGj9E,1556
+src/outputs/console.py,sha256=OwPP7fXCWFML2zB4d8AxPXikanebI8CrixbgsS3CMGM,1803
+src/outputs/factory.py,sha256=bNkBFHEsm3oOFIh5O6Gd9N1NpFQIBvO3woern8fw20g,4918
+src/outputs/file.py,sha256=6y585mxJS04MgTcMu5KPkJt_hm9qLjnbPEzD4MgrmI4,2594
+src/outputs/rest.py,sha256=C5VQOIocaIK9ZBqjjR4ZW6Vei8zC0uoA2rpv-v9e-RQ,8572
+src/pipeline/__init__.py,sha256=AouA0wkqDV1AU6P3fTaQTbmxZCBoNzXZzUWnpfmnm2Q,286
+src/pipeline/content_provider.py,sha256=v8-qW6bQ4YZ4XJgLWCGMrSQVbEbG2zHZDS985F9SKOM,854
+src/pipeline/detector_pipeline.py,sha256=5uJ_flXC_mNnkwtF5jyjBmYfWAWN4F4eHEMMQAZ5We0,27752
+src/pipeline/parsed_content_provider.py,sha256=B5QyqMpx_sscOOXQSVu92d_S2FqLSPKizYhwiS8jymw,1940
+src/sandbox/__init__.py,sha256=4t_V5Wf_2CGvtVMMblRMrAhl1T8uFpFxi-JZrelaers,123
+src/sandbox/runner.py,sha256=21L-POOKEChmOLhwyc2rGBGDpUpNVlPiG-Xqfh6ajDQ,5397
+src/sources/__init__.py,sha256=wYksO_0IcvlGXLouWapKyqzL0jG0El4rDDGRfwa4Zqk,3350
+src/sources/atlassian_common.py,sha256=9jqI03SgfstG-5nK5uHF8m4p6eVO263CkpCSim8h1iQ,11853
+src/sources/base.py,sha256=wTUGBvXqHYkPOICdWTPp31g42KCxXV74Db4QGjpKwnM,10163
+src/sources/dependencies.py,sha256=ei5P3S1CxnNN-zKlChKwzyWEeAApYggPM_YoqrSNWaU,2699
+src/sources/recipe_normalizer.py,sha256=JmTdLsqens7_-O1YG--VeAnbphCtfgFhLJ9tJugQHcc,5573
+src/sources/tabular_utils.py,sha256=AVpYLuNeud8WkMtdoNzrr_akV9yKN3t51ilkzOnnkGA,5387
+src/sources/azure_blob_storage/__init__.py,sha256=EAsp7N2Vpzc_S-ownm3-ieXVWZSIVXPPNiSlDGCyenI,81
+src/sources/azure_blob_storage/source.py,sha256=1hUKphzuyK5ga1cviQTgXQLeulYL173m8t0YgS2TOag,5384
+src/sources/confluence/__init__.py,sha256=VnD7SbvheqWwXS0bgxo9M561UOKgjENkwngwlLHJ500,69
+src/sources/confluence/source.py,sha256=rykXW-d8M0dUWCZjTg3fj0ut0140R5_oCbMMN3_x6jE,27381
+src/sources/databricks/__init__.py,sha256=yZZxIF-qhpt_W_zksFQoJGBqaIA40vQCyYLFSksGRFM,69
+src/sources/databricks/source.py,sha256=bDWjcg0Fs1vyMtyvzR3svWZyMHHS5JFuCgTiaNwOOWY,45219
+src/sources/google_cloud_storage/__init__.py,sha256=HSVm-DeqzcajfBkJdi1bsKC4r8N6c6ZD_ZQTpAVnqE0,85
+src/sources/google_cloud_storage/source.py,sha256=YUV5o9TY_CsRgDcma_5lugc1ltbQ1h36EtaMr6lSkl4,4454
+src/sources/hive/__init__.py,sha256=AYWKwROWOgaMDdRTakg5g3vqQqjECKXiozADPr4MeSM,57
+src/sources/hive/source.py,sha256=JAyrM1DBq1QWqI-L9rGlFXyN8G1Y0y0WnjhNptVEPmU,25949
+src/sources/jira/__init__.py,sha256=p3G96i94D6ZrdHKE6bzgVtYvO8h2-Aet4zERRYdJAyA,57
+src/sources/jira/source.py,sha256=Ogq1NiJ41k2MrjyIuakOLdxKYexXsARVfweaV7Obgiw,22027
+src/sources/mongodb/__init__.py,sha256=IcSTuVMB3JOXAjYpwFcFvRuc2a7m6xgZ1VG5AfM4eJU,63
+src/sources/mongodb/source.py,sha256=ydqBGxrryDtNG8n5LGxl4XmTYWDYHTQy2QcFREc-YtY,19985
+src/sources/mssql/__init__.py,sha256=Y2WuywS2C8lIsiwbikGKQQ9S3Pbp4X5cHyXiDNz8JPI,59
+src/sources/mssql/source.py,sha256=oTRbBRJlG4K-Em7LZ36k5ShQqYbhAvPtpXXqCbk0cOA,40106
+src/sources/mysql/__init__.py,sha256=V0hGtrFJLjGpc3iXzt2k8fH0WzAnyuuDG_2FogcwJBE,59
+src/sources/mysql/source.py,sha256=5RnjPBMYagQo0K9wr0tVjvhP4zBAUF2hFPzVBXg8Cpg,30257
+src/sources/neo4j/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/sources/neo4j/source.py,sha256=c230muZyihStMA1cOiSbNdP-v--DSwQR6018XryqTvM,18266
+src/sources/object_storage/base.py,sha256=_NJaqOyNBs_wJAp_wUcxcuekTLgKcB0xRActrztxgGM,24477
+src/sources/oracle/__init__.py,sha256=saYMyNR-UGniyVgLYS8u1PwPO5WQ_mEuq8WqYrl30rU,61
+src/sources/oracle/source.py,sha256=6iBoK4hLQia6sEUgIhPxGQVLwH0w-p6skL7BZo6PRYI,36949
+src/sources/postgresql/__init__.py,sha256=lHNYhsvG9fdnrr4b2Ya1mSdDdDRImmWOUEpQSXSu9dE,69
+src/sources/postgresql/source.py,sha256=nBCk4fXitI7-z6DKtSXRVzHcWPspY253O6olpsP8t8g,30234
+src/sources/powerbi/__init__.py,sha256=oDQQoV94r8xHqNjlCeFOULA-8Wyzr6tNCGznFEHEHF0,63
+src/sources/powerbi/source.py,sha256=NjKEOkm4lym2O6Tu7F87vJXwy9eMkQoMfTblPgXmqz8,28906
+src/sources/s3_compatible_storage/README.md,sha256=ud8h0cQ9OIwb2sw_3K3rBdTz2MCe2ratSKkcOGS1Lv4,2660
+src/sources/s3_compatible_storage/__init__.py,sha256=AH0ZNp34GXHC-RXnXk3wQg9HPgck8yTlFF4ygjixj0k,87
+src/sources/s3_compatible_storage/source.py,sha256=Jq9USIZ4wOZgaSwsAGl9YXPLrYHQMqroMjzdk7qno28,5578
+src/sources/servicedesk/__init__.py,sha256=LZAcPnWYPnLvH-FpqH4x_AtipFNToOOn86qaJXG5ohM,71
+src/sources/servicedesk/source.py,sha256=zzJffdcPlz51n8tOgdKHko1bOYCeU4Hq5BIM6g6HExc,23340
+src/sources/slack/__init__.py,sha256=k-3Or9wLb48KXjDXqQzrUc7VenJtb5SucyoFhGKdiow,59
+src/sources/slack/source.py,sha256=9cQI8e8fd1nzcZG2oaM72PxMB2vR5_Yf33IlCQGHEXA,18029
+src/sources/snowflake/__init__.py,sha256=NGXckaCGaD6eHCIlHs4aErhOxCc3BbNDPvdbV_xx24g,67
+src/sources/snowflake/source.py,sha256=fFen1NiCQOcDJ2SIldgeNgU1v8fjcW4EgfRbWsXyaSw,35565
+src/sources/tableau/__init__.py,sha256=Di1Bh9s9SYrUYg4xZhhAhl5HfoTt0B6WQB5SxVrQhbY,63
+src/sources/tableau/source.py,sha256=F-nX_DR1EO84OZMH2zCSfZgwCmibyI613kEB4YANnUM,30025
+src/sources/wordpress/__init__.py,sha256=T7v2TGUYiKzARpYk9bynxChY0P9GDDxpdbBz34x9g6o,67
+src/sources/wordpress/source.py,sha256=xs3dsc8FXXDJ5725eSaPvFnx2rN_g1520OWisceMlpA,21659
+src/utils/__init__.py,sha256=qHkwUQnAipyD7orncfDbJCaQ47mc02h90FgWy9ad_2o,25
+src/utils/content_extraction.py,sha256=Pqm_qMID2mQH1zc8099fNl-xIaQi3hOxQPWzK3yoKac,3082
+src/utils/file_parser.py,sha256=3LkNbnknDnaYJ8f8y2KzNiyVjSxXb6CGeFF1izqh06k,25875
+src/utils/hashing.py,sha256=T0GL1FWtG32QJID5RN3X-TzHHkolnNK6EfADvX6sdlE,2490
+src/utils/uv_sync.py,sha256=N-KELdr6T4rTOueXfoEEKb3-kneZP60KmAMnReihXWc,2583
+src/utils/validation.py,sha256=ab6OzB-GeZBMr413U10jG2FDiiWXCil-_e70T0BXwFE,1694
+classifyre_cli-0.4.2.dist-info/METADATA,sha256=lpA2EoqBNPEKdy8B43TvX-qgNAqdgVPlDEM5MdVZhvo,4221
+classifyre_cli-0.4.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+classifyre_cli-0.4.2.dist-info/entry_points.txt,sha256=edxllyMiIFfajgCZ3dTRACXYGC34ZX1AYTezMSR5E_8,45
+classifyre_cli-0.4.2.dist-info/RECORD,,

classifyre_cli-0.4.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

classifyre_cli-0.4.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+classifyre = src.main:main

src/__init__.py

@@ -0,0 +1 @@
+"""CLI source code."""

src/detectors/__init__.py

@@ -0,0 +1,105 @@
+"""Detector package for identifying sensitive content."""
+
+import importlib
+import logging
+import pkgutil
+
+from ..models.generated_detectors import DetectorConfig
+from .base import BaseDetector
+
+__all__ = ["BaseDetector", "get_detector", "list_available_detectors"]
+
+logger = logging.getLogger(__name__)
+
+_registry: dict[str, "type[BaseDetector]"] = {}
+
+
+def _discover_detectors() -> None:
+    """Auto-discover all BaseDetector subclasses in the detectors package."""
+    if _registry:
+        # Already discovered
+        return
+
+    logger.debug("Starting detector discovery...")
+
+    # Walk through all modules in the detectors package
+    for _loader, module_name, is_pkg in pkgutil.walk_packages(__path__, __name__ + "."):
+        if is_pkg:
+            continue
+
+        try:
+            # Import the module
+            module = importlib.import_module(module_name)
+
+            # Find all BaseDetector subclasses in the module
+            for attr_name in dir(module):
+                if attr_name.startswith("_"):
+                    continue
+                attr = getattr(module, attr_name)
+
+                # Check if it's a BaseDetector subclass (but not BaseDetector itself)
+                if (
+                    isinstance(attr, type)
+                    and issubclass(attr, BaseDetector)
+                    and attr is not BaseDetector
+                ):
+                    # Get detector name from class attribute or derive from class name
+                    detector_name = getattr(attr, "detector_name", None)
+                    if not detector_name:
+                        # Fallback: derive from class name
+                        detector_name = attr.__name__.replace("Detector", "").lower()
+                    if str(detector_name).startswith("_"):
+                        continue
+
+                    # Register the detector
+                    if detector_name in _registry:
+                        logger.warning(
+                            f"Duplicate detector name '{detector_name}' - "
+                            f"ignoring {module_name}.{attr_name}"
+                        )
+                    else:
+                        _registry[detector_name] = attr
+                        logger.debug(
+                            f"Registered detector '{detector_name}' from {module_name}.{attr_name}"
+                        )
+
+        except Exception as e:
+            logger.error(f"Failed to import {module_name}: {e}")
+
+
+def get_detector(detector_name: str, config: DetectorConfig | None = None) -> BaseDetector:
+    """
+    Factory function to create a detector instance.
+
+    Args:
+        detector_name: Name of the detector to create
+        config: Optional detector configuration
+
+    Returns:
+        Instance of the requested detector
+
+    Raises:
+        ValueError: If detector_name is not found in registry
+    """
+    # Ensure detectors are discovered
+    _discover_detectors()
+
+    if detector_name not in _registry:
+        available = ", ".join(sorted(_registry.keys()))
+        raise ValueError(f"Detector '{detector_name}' not found. Available: {available or 'none'}")
+
+    detector_class = _registry[detector_name]
+    return detector_class(config)
+
+
+def list_available_detectors() -> list[str]:
+    """
+    Return list of all registered detector names.
+
+    Returns:
+        Sorted list of detector names
+    """
+    # Ensure detectors are discovered
+    _discover_detectors()
+
+    return sorted(_registry.keys())

src/detectors/base.py

@@ -0,0 +1,97 @@
+"""Base detector interface for all detector implementations."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..models.generated_detectors import DetectorConfig
+from ..models.generated_single_asset_scan_results import DetectionResult
+
+
+class BaseDetector(ABC):
+    """
+    Base interface for all detector implementations.
+
+    All detectors must implement the detect() method and get_supported_content_types().
+    The base class provides common functionality like redaction and metadata retrieval.
+    """
+
+    detector_type: str = "base"
+    detector_name: str = "base"
+
+    def __init__(self, config: DetectorConfig | None = None):
+        self.config: DetectorConfig = config if config is not None else DetectorConfig()
+        self._initialized = False
+
+    @abstractmethod
+    async def detect(
+        self, content: str | bytes, content_type: str = "text/plain"
+    ) -> list[DetectionResult]:
+        """
+        Scan content and return findings.
+
+        Text detectors receive ``str``; image/binary detectors receive ``bytes``.
+        Implementations should return an empty list for unsupported content types.
+
+        Args:
+            content: The content to scan — text (str) or binary (bytes)
+            content_type: MIME type of content (e.g., 'text/plain', 'image/jpeg')
+
+        Returns:
+            List of detection results
+        """
+        pass
+
+    @abstractmethod
+    def get_supported_content_types(self) -> list[str]:
+        """
+        Return list of supported MIME types.
+
+        Returns:
+            List of MIME type strings (e.g., ['text/plain', 'application/json'])
+        """
+        pass
+
+    def get_metadata(self) -> dict[str, Any]:
+        """
+        Return detector metadata.
+
+        Returns:
+            Dictionary with detector type, name, supported content types, etc.
+        """
+        return {
+            "detector_type": self.detector_type,
+            "detector_name": self.detector_name,
+            "content_types": self.get_supported_content_types(),
+            "requires_gpu": self.requires_gpu(),
+        }
+
+    def requires_gpu(self) -> bool:
+        """
+        Return True if GPU is required for this detector.
+
+        Returns:
+            Boolean indicating GPU requirement
+        """
+        return False
+
+    def redact(self, content: str, findings: list[DetectionResult]) -> str:
+        """
+        Redact sensitive content based on findings.
+
+        Replaces each finding's matched_content with asterisks (*).
+
+        Args:
+            content: Original content
+            findings: List of detection results
+
+        Returns:
+            Redacted content string
+        """
+        redacted = content
+        for finding in findings:
+            if finding.location is None:
+                continue
+            if finding.matched_content:
+                mask = "*" * len(finding.matched_content)
+                redacted = redacted.replace(finding.matched_content, mask)
+        return redacted

src/detectors/broken_links/__init__.py

@@ -0,0 +1,3 @@
+from .detector import BrokenLinksDetector
+
+__all__ = ["BrokenLinksDetector"]