[BUG] Top-level semantica import fails due to circular import between pipeline_builder and pipeline_validator
bug
## Summary
After fixing the missing `Type` import in `semantica/utils/helpers.py`, top-level `import semantica` fails because the package eagerly imports the pipeline module, which has a circular import between `pipeline_builder.py` and `pipeline_validator.py`.
## Environment
- OS: Windows
- Python: 3.12
- Package: semantica
- Installed version reported by pip: 0.0.5
## Reproduction
```bash
python -m venv .venv312
.venv312\Scripts\activate
pip install semantica
python -c "import semantica"
```
Note: this appears after resolving the earlier missing `Type` import issue.
## Actual Result
```text
ImportError: cannot import name 'Pipeline' from partially initialized module 'semantica.pipeline.pipeline_builder'
(most likely due to a circular import)
```
The chain is approximately:
```text
semantica/__init__.py
-> semantica/pipeline/__init__.py
-> execution_engine.py
-> failure_handler.py
-> pipeline_builder.py
-> pipeline_validator.py
-> pipeline_builder.py
```
## Expected Result
`import semantica` should succeed without circular import errors.
## Why This Matters
Even when users only need concrete modules like:
```python
from semantica.ingest import FileIngestor
from semantica.split import StructuralChunker
from semantica.semantic_extract import NERExtractor
```
the top-level package import fails first because `semantica/__init__.py` eagerly imports pipeline components.
## Suggested Fix
Avoid eager pipeline imports in `semantica/__init__.py`, or refactor the circular dependency between `pipeline_builder.py` and `pipeline_validator.py`.
A lower-risk short-term option would be to lazy-load optional top-level exports so unrelated modules remain usable even if pipeline orchestration has an import issue.
关闭于 2026-05-04 1 条评论