Metadata-Version: 2.4
Name: isage-libs-intent
Version: 0.1.0.10
Summary: SAGE Libs Intent (L3) - Keyword-based and LLM-based intent classification for conversational AI
Author-email: IntelliStream Team <shuhao_zhang@hust.edu.cn>
License: MIT
Project-URL: Homepage, https://github.com/intellistream/sage-intent
Project-URL: Repository, https://github.com/intellistream/sage-intent
Project-URL: Documentation, https://github.com/intellistream/sage-intent#readme
Project-URL: Bug Tracker, https://github.com/intellistream/sage-intent/issues
Keywords: intent-recognition,intent-classification,nlu,conversational-ai,chatbot,llm,keyword-matching
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: openai<3.0.0,>=1.52.0
Requires-Dist: anthropic>=0.60.0
Provides-Extra: full
Provides-Extra: dev
Requires-Dist: isage-libs-intent[full]; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.4; extra == "dev"
Requires-Dist: isage-pypi-publisher>=0.2.0; extra == "dev"
Dynamic: license-file

# sage-libs-intent

L3 intent recognition package for SAGE agentic workflows.

- PyPI: `isage-libs-intent`
- Import path: `sage_libs.sage_agentic.intent`

## Scope

This package only provides intent recognition logic and data structures.

- `KeywordIntentRecognizer`: keyword and heuristic intent classification
- `LLMIntentRecognizer`: LLM-based intent classification
- `selector` mode: explicit integration with `isage-agentic` KeywordSelector
- `IntentClassifier`: chain wrapper over recognizers
- Intent catalog and typed intent/domain results

## Boundary

- Intent package does not depend on tool-selection internals.
- Recognizer build path is explicit and deterministic.
- Package exports are explicit and fail-fast.

## Recognizer Modes

- `keyword`: built-in keyword and heuristic recognizer
- `llm`: LLM recognizer via OpenAI-compatible gateway
- `selector`: explicit bridge to `isage-agentic` `KeywordSelector`

`selector` mode has no fallback behavior. If `isage-agentic` tool-selection modules are not available,
construction fails immediately with `ModuleNotFoundError`.

## Installation

```bash
pip install isage-libs-intent
```

## Quick Start

```python
import asyncio

from sage_libs.sage_agentic.intent import IntentClassifier


async def main() -> None:
    classifier = IntentClassifier(mode="keyword")
    result = await classifier.classify("请帮我找一下 SAGE 的安装文档")
    print(result.intent.value, result.confidence)


asyncio.run(main())
```

## LLM Recognizer Example

```python
import asyncio

from sage_libs.sage_agentic.intent import LLMIntentRecognizer, IntentRecognitionContext


async def main() -> None:
    recognizer = LLMIntentRecognizer(control_plane_url="http://localhost:8080/v1")
    result = await recognizer.classify(IntentRecognitionContext(message="Explain SAGE pipeline API"))
    print(result.intent.value, result.confidence)


asyncio.run(main())
```

## License

MIT
