Metadata-Version: 2.4
Name: cluxion-agentplugin-preprocessing
Version: 0.3.1
Summary: Universal agent plugin for Cluxion preprocessing, honesty contracts, clarification, Rust work queue, and resource-aware harness handoff.
Project-URL: Homepage, https://github.com/cluxion/cluxion-Agentplugin-preprocessing
Project-URL: Repository, https://github.com/cluxion/cluxion-Agentplugin-preprocessing
Project-URL: Issues, https://github.com/cluxion/cluxion-Agentplugin-preprocessing/issues
Author-email: cluxion <algocean1204@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agent,claude-code,cluxion,codex,hermes-agent,plugin,preprocessing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: psutil>=5.9
Requires-Dist: pyyaml>=6.0
Provides-Extra: browser
Requires-Dist: playwright>=1.49; extra == 'browser'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Requires-Dist: wheel>=0.45; extra == 'dev'
Description-Content-Type: text/markdown

# cluxion-Agentplugin-preprocessing

범용 에이전트 **전처리 플러그인** — **Hermes, Claude Code, Codex, Grok Build**에서 동일 core로 동작합니다.

**Repository:** https://github.com/cluxion/cluxion-Agentplugin-preprocessing

## 한 줄 요약

작업 시작 전에 **방향·정직함·큐**를 정리합니다. **연결된 AI**가 `cluxion_plan` 등 도구를 호출하고, JSON 계약(`answer_policy`, `host_execution`)에 따라 응답합니다. 플러그인은 추가 LLM 호출 없이 결정론적 plan만 반환합니다.

## 범용 에이전트 + Rust-First

| 계층 | 구현 |
|------|------|
| **Rust** (`cluxion-queue`) | SQLite 작업큐, atomic dispatch |
| **Python** (`cluxion_runtime`, adapter) | harness plan, 전처리, CLI |
| **Agent adapter** | `adapters/` — Hermes plugin, Claude skill, Codex snippet |

내부 hot path는 **Rust**. Python은 등록·JSON bridge·fallback입니다.

## 이 플러그인의 역할

- **정직함**: context 부족 시 모른다고 답하도록 `answer_policy` 생성
- **명확화**: 의도가 애매하면 큐 진입 전 질문 (`needs_clarification`)
- **작업큐**: 긴 입력을 segment로 분할, checksum 보존
- **리소스 admission**: RAM/CPU 압력에 따른 실행 허용 (결정론적)

**모델·OAuth·provider는 host agent 소유.** Cluxion은 plan·게이트·큐 메타데이터만 반환합니다.

## 연결된 AI가 하는 일

| 단계 | 동작 |
|------|------|
| 요청 수신 | `cluxion_plan` 또는 `cluxion-runtime plan` |
| 명확화 필요 | `clarification.questions`로 사용자에게 질문 |
| queued 모드 | `cluxion_queue_next` → 처리 → `cluxion_queue_record` → `cluxion_queue_brief` |
| 응답 | `answer_policy.required_checks` 준수 |

## 설계 요약

```
User prompt → cluxion_plan → [clarification?] → preprocessing mode
           → answer_policy + host_execution
           → (queued) queue_next/record/brief
```

**설계 원칙**

1. **추가 AI preflight 없음** — 결정론적 plan
2. 짧은 일반 질문은 `simple_answer` fast path
3. 불확실 시 fake success 금지 — `needs_clarification`, `unknown_after_check`
4. **opt-in** — 사용자 동의 없이 권한 확대 없음

## 빠른 시작

```bash
pip install cluxion-agentplugin-preprocessing
cluxion-preprocess check
cluxion-preprocess enable    # Hermes
```

```bash
cluxion-runtime plan --surface hermes --prompt "작업 설명"
```

## 도구 (`cluxion` toolset, 10 tools)

| Tool | 설명 |
|------|------|
| `cluxion_plan` | 전처리·방향·큐·리소스 계획 |
| `cluxion_clarify` | 명확화 질문 목록 |
| `cluxion_bootstrap` | 로컬 runtime 의존성 설치/업그레이드 (예: vllm-mlx) |
| `cluxion_serve_local` | Cluxion-managed vLLM-MLX 로컬 endpoint 준비/시작 |
| `cluxion_hermes_config` | 로컬 OpenAI-compatible endpoint용 Hermes provider config |
| `cluxion_queue_next` / `record` / `brief` | segment 큐 |
| `cluxion_context_compress` | context 사용률 초과 시 결정론적 압축 (pinned/recent 보존) |
| `cluxion_guard` | 실시간 리소스 guard (`status`/`start`/`stop`/`enforce`/`auto-enforce`) |

Hermes에서는 `on_session_start` hook이 guard daemon을 자동 시작합니다. `CLUXION_GUARD_AUTOSTART=0` 또는 `false`로 끌 수 있고, `post_tool_call` hook은 기본 30초마다 report-only `auto_enforce(dry_run=True)`를 실행합니다. 실제 적용은 `CLUXION_GUARD_AUTO_APPLY=1` 또는 `true`일 때만 켜집니다.

## 문서

- [Docs/README.md](Docs/README.md) — **처음 읽는 분** + 목차
- [Docs/architecture.md](Docs/architecture.md)
- [Docs/design.md](Docs/design.md)
- [Docs/installation.md](Docs/installation.md)
- [Docs/tools.md](Docs/tools.md)
- [Docs/agent-surfaces.md](Docs/agent-surfaces.md)
- [Docs/rust-architecture.md](Docs/rust-architecture.md)

## License

Apache-2.0
