# Story 5.17: BaseFilter Export and Import Consistency

## Status: Complete

## Priority: High

## Estimated Effort: Small (< 1 day)

## Dependencies: None

## Epic: Plugin System Consistency

---

## Context

The `BaseFilter` protocol is correctly imported in `fapilog/plugins/__init__.py` and included in `__all__`, but there are inconsistencies in how it's documented and used compared to other base protocols.

Additionally, the contracts-and-versioning documentation mentions `BaseFilter` but the main plugins index and some internal code paths may not consistently reference it.

---

## Problem Statement

### Current State

1. **Import is correct:**

   ```python
   # src/fapilog/plugins/__init__.py
   from .filters import BaseFilter
   ```

2. **Export is correct:**

   ```python
   __all__ = [
       "BaseEnricher",
       "BaseProcessor",
       "BaseSink",
       "BaseRedactor",
       "BaseFilter",  # ✅ Present
       ...
   ]
   ```

3. **Documentation inconsistency:**

   - `docs/plugins/contracts-and-versioning.md` mentions `BaseFilter`
   - `docs/plugins/authoring.md` example import doesn't show `BaseFilter`
   - Some examples only show four protocols

4. **Usage inconsistency:**
   - `testing/validators.py` has `validate_filter` but separate from others
   - Not all test files import `BaseFilter` from the public path

---

## Acceptance Criteria

### AC1: Documentation Consistency

- [ ] Update `docs/plugins/authoring.md` to include `BaseFilter` in import example
- [ ] Update `docs/plugins/contracts-and-versioning.md` to consistently list all five protocols
- [ ] Ensure `docs/plugins/index.md` mentions filters in the overview

### AC2: Example Code Consistency

- [ ] All documentation examples that show protocol imports include `BaseFilter`
- [ ] Add filter examples alongside other plugin type examples

### AC3: Test Import Consistency

- [ ] Verify `BaseFilter` can be imported from `fapilog.plugins`
- [ ] Add explicit test for this import path

---

## Technical Design

### 1. Documentation Updates

#### docs/plugins/authoring.md

Update the protocols section:

````markdown
## Protocols

Author implementations should satisfy the runtime-checkable Protocol for their type:

```python
from fapilog.plugins import (
    BaseSink,
    BaseProcessor,
    BaseEnricher,
    BaseRedactor,
    BaseFilter,
)
```
````

All interfaces are async-first and must contain errors rather than raising into the core pipeline.

````

#### docs/plugins/contracts-and-versioning.md

Update the protocols list:

```markdown
## Public Protocols

Fapilog exposes runtime-checkable Protocols for all plugin types. Implementations should be async-first and resilient.

- Sinks: `fapilog.plugins.sinks.BaseSink`
- Enrichers: `fapilog.plugins.enrichers.BaseEnricher`
- Processors: `fapilog.plugins.processors.BaseProcessor`
- Redactors: `fapilog.plugins.redactors.BaseRedactor`
- Filters: `fapilog.plugins.filters.BaseFilter`

These are re-exported in `fapilog.plugins` for convenient import:

```python
from fapilog.plugins import BaseSink, BaseEnricher, BaseProcessor, BaseRedactor, BaseFilter
````

````

### 2. Add Import Test

```python
# tests/unit/test_public_api_init.py (add to existing)

def test_basefilter_importable_from_plugins():
    """BaseFilter should be importable from fapilog.plugins."""
    from fapilog.plugins import BaseFilter

    assert hasattr(BaseFilter, "filter")
    assert hasattr(BaseFilter, "name")


def test_all_base_protocols_importable():
    """All base protocols should be importable from fapilog.plugins."""
    from fapilog.plugins import (
        BaseSink,
        BaseEnricher,
        BaseProcessor,
        BaseRedactor,
        BaseFilter,
    )

    # Verify they're all protocols with expected methods
    assert hasattr(BaseSink, "write")
    assert hasattr(BaseEnricher, "enrich")
    assert hasattr(BaseProcessor, "process")
    assert hasattr(BaseRedactor, "redact")
    assert hasattr(BaseFilter, "filter")
````

---

## Test Plan

### Unit Tests

1. **test_public_api_init.py**
   - Test `BaseFilter` import from `fapilog.plugins`
   - Test all five protocols importable together
   - Test protocol attributes exist

### Documentation Tests

1. Verify code examples in docs are executable
2. Run doctest on updated documentation

---

## Documentation Updates

Files to update:

1. `docs/plugins/authoring.md` - Add BaseFilter to imports
2. `docs/plugins/contracts-and-versioning.md` - Ensure consistency
3. `docs/plugins/index.md` - Mention filters in overview
4. Any examples that show partial protocol imports

---

## Backwards Compatibility

- No breaking changes
- Documentation-only updates
- Import paths already work correctly

---

## Related Stories

- Story 5.2: Add filter plugin type
- Story 5.16: Add filter to plugin type metadata validation
- Story 5.4: Plugin testing guide
