ff-taskforce 0.1.0__py3-none-any.whl

ff_taskforce-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: ff-taskforce
+Version: 0.1.0
+Summary: Multi-LLM roundtable for diverse perspective gathering
+Project-URL: Repository, https://github.com/gatesplan/taskforce
+Project-URL: Issues, https://github.com/gatesplan/taskforce/issues
+License: MIT
+License-File: LICENSE
+Keywords: agent,llm,mcp,multi-model,roundtable
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: litellm
+Requires-Dist: loguru
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv
+Provides-Extra: mcp
+Requires-Dist: mcp; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# taskforce
+
+AI agent-oriented multi-LLM roundtable library.
+
+Multiple top-tier LLMs (GPT, Grok, Claude, Gemini) are queried in parallel with the same agenda, and the collected opinions are classified into **common / divergent / unique** perspectives, returned as a structured `IdeaPool`.
+
+**This package is designed for AI agents, not for direct human use.**
+The primary interface is the MCP wrapper (`roundtable_discuss` tool), which allows agents to invoke a roundtable discussion as a tool call. A Python API is also available for programmatic integration.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install taskforce
+```
+
+For MCP server support:
+
+```bash
+pip install taskforce[mcp]
+```
+
+### 2. Set environment variables
+
+At least two provider API keys are required (one will be excluded as the caller).
+`XAI_API_KEY` is always required (used by the summarizer).
+
+```
+OPENAI_API_KEY=sk-...
+XAI_API_KEY=xai-...
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=AI...
+```
+
+### 3. Use as MCP tool (recommended for agents)
+
+Add to your MCP server config:
+
+`TASKFORCE_CALLER_PROVIDER` is the provider of the agent that will call this tool.
+The matching provider's model is excluded from the panel -- querying the same model that is already reasoning adds no diversity.
+For example, if Claude Code is the caller, set it to `"anthropic"` so Claude is excluded from the panel.
+
+```json
+{
+  "mcpServers": {
+    "taskforce": {
+      "command": "python",
+      "args": ["-m", "taskforce.mcp_wrapper"],
+      "env": {
+        "TASKFORCE_CALLER_PROVIDER": "anthropic"
+      }
+    }
+  }
+}
+```
+
+The agent can then call the `roundtable_discuss` tool with `agenda` and `context` parameters.
+
+### 4. Use as Python library
+
+```python
+from taskforce import Taskforce
+
+tf = Taskforce(caller_provider="anthropic")
+pool = tf.discuss(
+    agenda="Evaluate the trade-offs of approach A vs B",
+    context="<detailed context here>"
+)
+
+# pool.common    -- list[str]: points most models agree on
+# pool.divergent -- list[DivergentPoint]: topics with differing positions
+# pool.unique    -- list[UniquePoint]: points raised by only one model
+```
+
+## Important Notes
+
+- **Paid API calls.** Every `discuss()` invocation calls multiple LLM APIs in parallel. Agents should confirm with the user before calling.
+- **caller_provider exclusion.** The model from the same provider as the calling agent is excluded from the panel to maximize perspective diversity.
+- **XAI_API_KEY is mandatory.** The summarizer (grok-4-1-fast-non-reasoning) always uses the XAI key.
+- **Rich context matters.** Input tokens are cheap. Provide as much context as possible -- specifications, constraints, background, decisions already made -- so the panel can give concrete, actionable opinions instead of generic advice.
+
+## API
+
+### `Taskforce(caller_provider, dotenv_path=None)`
+
+- `caller_provider` (`str`): The LLM provider of the calling agent (e.g. `"anthropic"`, `"openai"`). That provider's model is excluded from the panel.
+- `dotenv_path` (`str | None`): Path to `.env` file. Defaults to auto-discovery.
+
+### `Taskforce.discuss(agenda, context="") -> IdeaPool`
+
+Synchronous wrapper. Queries the panel, summarizes, and returns an `IdeaPool`.
+
+### `Taskforce.discuss_async(agenda, context="") -> IdeaPool`
+
+Async version for use in async contexts.
+
+### `IdeaPool`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agenda` | `str` | The original agenda |
+| `common` | `list[str]` | Points most models agree on |
+| `divergent` | `list[DivergentPoint]` | Topics with differing positions (`topic`, `positions: dict[model, position]`) |
+| `unique` | `list[UniquePoint]` | Points from a single model (`point`, `source_model`) |
+| `total_cost` | `float` | Total API cost (USD) |
+| `total_tokens` | `int` | Total tokens consumed |
+
+## License
+
+MIT

ff_taskforce-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+taskforce/__init__.py,sha256=RbWmYRJP0g3wcDAMLkT7eonFt2sJAOSPbVM6KQqf96g,68
+taskforce/for-agent-layerinfo.md,sha256=UiwhcCYsbgFRDW0SnzjsqxFQqrsI9T9mvkHveibruqk,472
+taskforce/l1/__init__.py,sha256=WPhPxdLAWkaxuHfzNpxI3vKIDlFa9Q6w5cALlfHlFJM,161
+taskforce/l1/for-agent-layerinfo-l1.md,sha256=rUXo5NFVScE3gAKChddkgf8pjNg0FWHg32N2k7lFw3E,327
+taskforce/l1/schema/__init__.py,sha256=WPhPxdLAWkaxuHfzNpxI3vKIDlFa9Q6w5cALlfHlFJM,161
+taskforce/l1/schema/for-agent-moduleinfo.md,sha256=17kQf4-KSmd6FIei2PbtbKiqlBlbR4FZvDFopb51PmY,1122
+taskforce/l1/schema/schema.py,sha256=BRnavvnZp3NA9-vXqxpTAFW1utBoJsd2HNKlwtkUP1g,608
+taskforce/l2/__init__.py,sha256=-m0agG1snzxPrr8Rud9hS7m4msCjp2KrO_FmHBkUIUo,207
+taskforce/l2/for-agent-layerinfo-l2.md,sha256=Y5QgI7C7Coz3N5t_tKurfJy4Pgy8mXreRQuTMrRyf-0,622
+taskforce/l2/config/__init__.py,sha256=IMyl3II4ECLtsJ0CcDUYfR-h8pkWm1Zk7ChE-aX-aNU,55
+taskforce/l2/config/config.py,sha256=W1igecQak7HiNOMk0T6Y07g6tDDypQ3ehWgIpsXhE_Y,2494
+taskforce/l2/config/for-agent-moduleinfo.md,sha256=sBvvLzUEJQVXawgNSIlOOyFYs0Uq4b7OItbYFfasKF4,781
+taskforce/l2/cost_logger/__init__.py,sha256=J2eqb0NP92XagSO7gIt5s3Jm_z46trkzYDRbzppU9QU,62
+taskforce/l2/cost_logger/cost_logger.py,sha256=oHFrnrfxFDmFYyMX-WsMvmfGIoL_3IYKqCziStZN148,1549
+taskforce/l2/cost_logger/for-agent-moduleinfo.md,sha256=ddRq_KVjbwJndkfeKluB6bfx3xnWhITc36FFRhOJZQA,595
+taskforce/l2/panelist/__init__.py,sha256=NlGY0oet_C5AWApsCbkOaxvznDPwIOqKqvejKUT2M5U,55
+taskforce/l2/panelist/for-agent-moduleinfo.md,sha256=_g7M5mTuqLkSlFqYbvJoB7wtR2IR_cNYOoZ0vh8rERU,582
+taskforce/l2/panelist/panelist.py,sha256=rZWbcDHl6KAwTGh6ZD0R97T4g04ZjWXMbOg2ZBROTOk,1897
+taskforce/l2/session_logger/__init__.py,sha256=i5R8g-8QNrQWshlGIqV91XumjZezfrZRYOJdmgtWuKQ,71
+taskforce/l2/session_logger/for-agent-moduleinfo.md,sha256=l6_lgosPqp3y4beqds7U1L6S9hjGIQbhkuxcoK96GfE,611
+taskforce/l2/session_logger/session_logger.py,sha256=PDIVd9WTNTqpvLq8QStPsyFFykPgVp7cL51-8Q-jtzc,1593
+taskforce/l3/__init__.py,sha256=9KyOzm-QQS3MPFaP3sJQIJqUXNxfhTP5m_nLnsUn3VU,61
+taskforce/l3/for-agent-layerinfo-l3.md,sha256=Vuo2ofbPbVRMKzLGwBskgZ5ckdta2mi2YRgzHbOnvIg,290
+taskforce/l3/roundtable/__init__.py,sha256=9KyOzm-QQS3MPFaP3sJQIJqUXNxfhTP5m_nLnsUn3VU,61
+taskforce/l3/roundtable/for-agent-moduleinfo.md,sha256=AALwBRRZc6_nvejn8XV24N4DkRmvLF_tbu-sLS7yJaI,885
+taskforce/l3/roundtable/roundtable.py,sha256=DOb8aysINeQS4bp_21LW9CQAYP4GBeO-1Win-Fde2fA,3982
+taskforce/l4/__init__.py,sha256=EnxeuegsZP8DT8D0Ziy36zbVvpeTUUKjP2BfAMzwSV4,65
+taskforce/l4/for-agent-layerinfo-l4.md,sha256=ynFygOe89Z06cNLwOkoztW1AEr7rFUq6a_azmNAo2Mo,229
+taskforce/l4/taskforce_facade/__init__.py,sha256=EnxeuegsZP8DT8D0Ziy36zbVvpeTUUKjP2BfAMzwSV4,65
+taskforce/l4/taskforce_facade/for-agent-moduleinfo.md,sha256=mju3fdECZN0m0hcoIpklP37DeZlV2wkIVROovNLGIoY,711
+taskforce/l4/taskforce_facade/taskforce_facade.py,sha256=6LlSMwa30NPLaknSCXuiaDM4-sTrc752P4xgs8OwemQ,1437
+taskforce/mcp_wrapper/__init__.py,sha256=ethK8wvFtEwoanJ7QvREYfFkm2430FtU5SPuipmEGOw,48
+taskforce/mcp_wrapper/__main__.py,sha256=U1mIekzzLhZIprEhZ7yLp_ysVnYjukAE-XLJe_8KBPg,40
+taskforce/mcp_wrapper/mcp_wrapper.py,sha256=_UWYQwswwMi8n0RVrAcCS06yJJ6KfheyMQpr1cKdxoE,1875
+ff_taskforce-0.1.0.dist-info/METADATA,sha256=zixX-N7SUyozOI1OMMpckDGR72vrZsgxJdVkGUI4WGQ,4712
+ff_taskforce-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ff_taskforce-0.1.0.dist-info/licenses/LICENSE,sha256=Is6uQxKak3NHGPiVNoiMJUOEmLcvt5yqetu2h3RYTlI,1079
+ff_taskforce-0.1.0.dist-info/RECORD,,

ff_taskforce-0.1.0.dist-info/WHEEL

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

ff_taskforce-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taskforce contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taskforce/__init__.py

@@ -0,0 +1,3 @@
+from .l4.taskforce_facade import Taskforce
+
+__all__ = ['Taskforce']

taskforce/for-agent-layerinfo.md

@@ -0,0 +1,16 @@
+# taskforce
+
+## l1
+- schema: 데이터 모델 (ModelEntry, Opinion, IdeaPool)
+
+## l2
+- config: .env 로드, 모델 레지스트리, caller 제외 로직
+- panelist: LiteLLM 래퍼, 개별 모델 async 호출
+- session_logger: 세션 전문 로그 (~/.taskforce/logs/)
+- cost_logger: 비용 요약 로그 (~/.taskforce/cost_logs/)
+
+## l3
+- roundtable: 병렬 질의 + summarizer 분류 취합
+
+## l4
+- taskforce_facade: 최상위 퍼사드, 초기화/discuss/로그 기록

taskforce/l1/__init__.py

@@ -0,0 +1,3 @@
+from .schema import ModelEntry, Opinion, DivergentPoint, UniquePoint, IdeaPool
+
+__all__ = ['ModelEntry', 'Opinion', 'DivergentPoint', 'UniquePoint', 'IdeaPool']

taskforce/l1/for-agent-layerinfo-l1.md

@@ -0,0 +1,8 @@
+# l1
+
+## schema
+ModelEntry(provider: str, model_id: str, api_key: str, display_name: str)
+Opinion(model_name: str, content: str)
+DivergentPoint(topic: str, positions: dict[str, str])
+UniquePoint(point: str, source_model: str)
+IdeaPool(agenda: str, common: list[str], divergent: list[DivergentPoint], unique: list[UniquePoint])

taskforce/l1/schema/__init__.py

@@ -0,0 +1,3 @@
+from .schema import ModelEntry, Opinion, DivergentPoint, UniquePoint, IdeaPool
+
+__all__ = ['ModelEntry', 'Opinion', 'DivergentPoint', 'UniquePoint', 'IdeaPool']

taskforce/l1/schema/for-agent-moduleinfo.md

@@ -0,0 +1,47 @@
+# Schema
+
+pydantic 데이터 모델 정의.
+
+## ModelEntry
+
+LLM 프로바이더 모델 정보.
+
+### Properties
+provider: str              # 프로바이더명 (openai, xai, anthropic, gemini)
+model_id: str              # LiteLLM 모델 ID
+api_key: str               # API 키
+display_name: str          # 표시용 이름
+
+## Opinion
+
+패널리스트 응답.
+
+### Properties
+model_name: str            # 응답한 모델 표시명
+content: str               # 응답 전문
+
+## DivergentPoint
+
+모델 간 의견이 갈리는 지점.
+
+### Properties
+topic: str                 # 쟁점
+positions: dict[str, str]  # {model_name: 해당 입장}
+
+## UniquePoint
+
+한 모델만 제시한 고유 관점.
+
+### Properties
+point: str                 # 고유 관점 내용
+source_model: str          # 제시한 모델명
+
+## IdeaPool
+
+라운드테이블 결과. 구조화된 아이디어 풀.
+
+### Properties
+agenda: str                        # 원본 의제
+common: list[str]                  # 다수 모델 공통 포인트
+divergent: list[DivergentPoint]    # 이견 지점
+unique: list[UniquePoint]          # 고유 관점

taskforce/l1/schema/schema.py

@@ -0,0 +1,35 @@
+from pydantic import BaseModel
+
+
+class ModelEntry(BaseModel):
+    provider: str
+    model_id: str
+    api_key: str
+    display_name: str
+    extra_params: dict = {}
+
+
+class Opinion(BaseModel):
+    model_name: str
+    content: str
+    cost: float = 0.0
+    tokens: int = 0
+
+
+class DivergentPoint(BaseModel):
+    topic: str
+    positions: dict[str, str]
+
+
+class UniquePoint(BaseModel):
+    point: str
+    source_model: str
+
+
+class IdeaPool(BaseModel):
+    agenda: str
+    common: list[str]
+    divergent: list[DivergentPoint]
+    unique: list[UniquePoint]
+    total_cost: float = 0.0
+    total_tokens: int = 0

taskforce/l2/__init__.py

@@ -0,0 +1,6 @@
+from .config import EnvConfig
+from .panelist import Panelist
+from .session_logger import SessionLogger
+from .cost_logger import CostLogger
+
+__all__ = ['EnvConfig', 'Panelist', 'SessionLogger', 'CostLogger']

taskforce/l2/config/__init__.py

@@ -0,0 +1,3 @@
+from .config import EnvConfig
+
+__all__ = ['EnvConfig']

taskforce/l2/config/config.py

@@ -0,0 +1,65 @@
+import os
+
+from dotenv import load_dotenv
+from loguru import logger
+
+from ...l1.schema import ModelEntry
+
+# 환경변수 -> 패널 모델 매핑
+_PANEL_REGISTRY = [
+    {"env_key": "OPENAI_API_KEY", "provider": "openai", "model_id": "gpt-5.4", "display_name": "GPT 5.4"},
+    {"env_key": "XAI_API_KEY", "provider": "xai", "model_id": "grok-4-1-fast-reasoning", "display_name": "Grok 4-1"},
+    {"env_key": "ANTHROPIC_API_KEY", "provider": "anthropic", "model_id": "claude-opus-4", "display_name": "Claude opus-4"},
+    {"env_key": "GEMINI_API_KEY", "provider": "gemini", "model_id": "gemini-2.5-pro", "display_name": "Gemini 2.5 Pro"},
+]
+
+_SUMMARIZER_MODEL_ID = "grok-4-1-fast-non-reasoning"
+_SUMMARIZER_DISPLAY_NAME = "Grok 4-1 Fast"
+
+
+class EnvConfig:
+    def __init__(self, caller_provider: str, dotenv_path: str | None = None):
+        self.caller_provider = caller_provider
+
+        if dotenv_path:
+            load_dotenv(dotenv_path)
+        else:
+            load_dotenv()
+
+        # caller_provider 제외, 키가 있는 모델만 패널 등록
+        self.panel_models: list[ModelEntry] = []
+        for entry in _PANEL_REGISTRY:
+            api_key = os.getenv(entry["env_key"], "")
+            if not api_key:
+                continue
+            if entry["provider"] == caller_provider:
+                logger.debug(f"패널 제외 (caller): {entry['display_name']}")
+                continue
+            self.panel_models.append(ModelEntry(
+                provider=entry["provider"],
+                model_id=entry["model_id"],
+                api_key=api_key,
+                display_name=entry["display_name"],
+                extra_params=entry.get("extra_params", {}),
+            ))
+            logger.debug(f"패널 등록: {entry['display_name']}")
+
+        if not self.panel_models:
+            raise ValueError("활성 패널 모델이 없습니다. .env에 API 키를 설정하세요.")
+
+        # Summarizer (XAI_API_KEY 공유)
+        xai_key = os.getenv("XAI_API_KEY", "")
+        if not xai_key:
+            raise ValueError("XAI_API_KEY 필요 (summarizer용)")
+
+        self.summarizer_model = ModelEntry(
+            provider="xai",
+            model_id=_SUMMARIZER_MODEL_ID,
+            api_key=xai_key,
+            display_name=_SUMMARIZER_DISPLAY_NAME,
+        )
+
+        logger.info(f"EnvConfig 초기화: 패널 {len(self.panel_models)}개, caller={caller_provider}")
+
+    def get_active_panels(self) -> list[ModelEntry]:
+        return self.panel_models

taskforce/l2/config/for-agent-moduleinfo.md

@@ -0,0 +1,24 @@
+# Config
+
+.env에서 API 키를 로드하고 모델 레지스트리를 구성.
+
+## EnvConfig
+
+환경변수 기반 모델 구성. caller_provider 모델은 패널에서 제외.
+
+### Properties
+caller_provider: str                 # 호출자 프로바이더
+panel_models: list[ModelEntry]       # 활성 패널 모델 목록
+summarizer_model: ModelEntry         # Summarizer 모델 (grok-4-1-fast-non-reasoning)
+
+### __init__
+__init__(caller_provider: str, dotenv_path: str | None = None)
+    raise ValueError
+    .env 로드 후 키가 있고 caller가 아닌 모델만 패널 등록.
+    활성 패널 0개이면 ValueError.
+    XAI_API_KEY 없으면 ValueError (summarizer 필수).
+
+### Methods
+
+get_active_panels() -> list[ModelEntry]
+    등록된 패널 모델 목록 반환.

taskforce/l2/cost_logger/__init__.py

@@ -0,0 +1,3 @@
+from .cost_logger import CostLogger
+
+__all__ = ['CostLogger']

taskforce/l2/cost_logger/cost_logger.py

@@ -0,0 +1,48 @@
+import json
+from datetime import datetime
+from pathlib import Path
+
+from loguru import logger
+
+from ...l1.schema import Opinion
+
+_DEFAULT_DIR = Path.home() / ".taskforce" / "cost_logs"
+
+
+class CostLogger:
+    def __init__(self, log_dir: Path | None = None):
+        self.log_dir = log_dir or _DEFAULT_DIR
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def log(self, agenda: str, opinions: list[Opinion], summarizer_cost: float = 0.0, summarizer_tokens: int = 0) -> None:
+        timestamp = datetime.now().isoformat()
+
+        models = []
+        for op in opinions:
+            models.append({
+                "model_name": op.model_name,
+                "tokens": op.tokens,
+                "cost": op.cost,
+            })
+
+        total_cost = sum(op.cost for op in opinions) + summarizer_cost
+        total_tokens = sum(op.tokens for op in opinions) + summarizer_tokens
+
+        record = {
+            "timestamp": timestamp,
+            "agenda": agenda[:100],
+            "models": models,
+            "summarizer_cost": summarizer_cost,
+            "summarizer_tokens": summarizer_tokens,
+            "total_cost": total_cost,
+            "total_tokens": total_tokens,
+        }
+
+        # 월별 파일로 분리
+        month = datetime.now().strftime("%Y-%m")
+        filepath = self.log_dir / f"{month}.jsonl"
+
+        with open(filepath, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+        logger.debug(f"비용 로그 기록: ${total_cost:.4f}, {total_tokens} tokens")

taskforce/l2/cost_logger/for-agent-moduleinfo.md

@@ -0,0 +1,21 @@
+# CostLogger
+
+비용 요약 로그 기록. 모델별 tokens/cost를 JSONL로 저장.
+
+## CostLogger
+
+~/.taskforce/cost_logs/ 에 월별 JSONL 파일로 누적 기록.
+
+### Properties
+log_dir: Path              # 로그 디렉토리 경로
+
+### __init__
+__init__(log_dir: Path | None = None)
+    log_dir 미지정 시 ~/.taskforce/cost_logs/ 사용.
+    디렉토리 자동 생성.
+
+### Methods
+
+log(agenda: str, opinions: list[Opinion], summarizer_cost: float = 0.0, summarizer_tokens: int = 0) -> None
+    비용 레코드를 월별 파일에 append.
+    모델별 tokens/cost + 총계 기록.

taskforce/l2/for-agent-layerinfo-l2.md

@@ -0,0 +1,17 @@
+# l2
+
+## config
+EnvConfig.__init__(caller_provider: str, dotenv_path: str | None = None)
+EnvConfig.get_active_panels() -> list[ModelEntry]
+
+## panelist
+Panelist.__init__(model_entry: ModelEntry)
+Panelist.ask_async(prompt: str, system_msg: str = "") -> Opinion
+
+## session_logger
+SessionLogger.__init__(log_dir: Path | None = None)
+SessionLogger.log(agenda: str, context: str, opinions: list[Opinion], summarizer_output: str = "") -> Path
+
+## cost_logger
+CostLogger.__init__(log_dir: Path | None = None)
+CostLogger.log(agenda: str, opinions: list[Opinion], summarizer_cost: float = 0.0, summarizer_tokens: int = 0) -> None

taskforce/l2/panelist/__init__.py

@@ -0,0 +1,3 @@
+from .panelist import Panelist
+
+__all__ = ['Panelist']

taskforce/l2/panelist/for-agent-moduleinfo.md

@@ -0,0 +1,23 @@
+# Panelist
+
+LiteLLM 래퍼. 개별 LLM 모델에 async 질의.
+
+## Panelist
+
+ModelEntry를 받아 LiteLLM acompletion으로 호출.
+
+### Properties
+model_entry: ModelEntry    # 모델 정보
+
+### __init__
+__init__(model_entry: ModelEntry)
+    ModelEntry 기반으로 LiteLLM 모델 ID 해석.
+    OpenAI는 model_id만, 나머지는 provider/model_id 형식.
+
+### Methods
+
+ask_async(prompt: str, system_msg: str = "") -> Opinion
+    raise Exception
+    LiteLLM acompletion으로 모델 호출.
+    system_msg가 있으면 system role로 전달.
+    실패 시 원본 예외 전파.

taskforce/l2/panelist/panelist.py

@@ -0,0 +1,52 @@
+import litellm
+from loguru import logger
+
+from ...l1.schema import ModelEntry, Opinion
+
+
+class Panelist:
+    def __init__(self, model_entry: ModelEntry):
+        self.model_entry = model_entry
+        self._litellm_model = self._resolve_model_id()
+
+    def _resolve_model_id(self) -> str:
+        # LiteLLM: OpenAI는 model_id만, 나머지는 provider/model_id
+        if self.model_entry.provider == "openai":
+            return self.model_entry.model_id
+        return f"{self.model_entry.provider}/{self.model_entry.model_id}"
+
+    async def ask_async(self, prompt: str, system_msg: str = "") -> Opinion:
+        messages = []
+        if system_msg:
+            messages.append({"role": "system", "content": system_msg})
+        messages.append({"role": "user", "content": prompt})
+
+        try:
+            response = await litellm.acompletion(
+                model=self._litellm_model,
+                messages=messages,
+                api_key=self.model_entry.api_key,
+                **self.model_entry.extra_params,
+            )
+            content = response.choices[0].message.content
+
+            # 비용/토큰 추출
+            cost = 0.0
+            tokens = 0
+            try:
+                cost = litellm.completion_cost(completion_response=response)
+            except Exception:
+                pass
+            if hasattr(response, "usage") and response.usage:
+                tokens = getattr(response.usage, "total_tokens", 0)
+
+            logger.debug(f"{self.model_entry.display_name} 응답: {len(content)} chars, {tokens} tokens, ${cost:.4f}")
+            return Opinion(
+                model_name=self.model_entry.display_name,
+                content=content,
+                cost=cost,
+                tokens=tokens,
+            )
+        except Exception as e:
+            logger.error(f"{self.model_entry.display_name} 호출 실패: {e}")
+            raise

taskforce/l2/session_logger/__init__.py

@@ -0,0 +1,3 @@
+from .session_logger import SessionLogger
+
+__all__ = ['SessionLogger']

taskforce/l2/session_logger/for-agent-moduleinfo.md

@@ -0,0 +1,22 @@
+# SessionLogger
+
+세션 전문 로그 기록. prompt, response 원문을 JSONL로 저장.
+
+## SessionLogger
+
+~/.taskforce/logs/ 에 세션별 JSONL 파일 생성.
+
+### Properties
+log_dir: Path              # 로그 디렉토리 경로
+
+### __init__
+__init__(log_dir: Path | None = None)
+    log_dir 미지정 시 ~/.taskforce/logs/ 사용.
+    디렉토리 자동 생성.
+
+### Methods
+
+log(agenda: str, context: str, opinions: list[Opinion], summarizer_output: str = "") -> Path
+    세션 로그 파일 생성.
+    request, opinion, summarizer 레코드를 JSONL로 기록.
+    생성된 파일 경로 반환.

taskforce/l2/session_logger/session_logger.py

@@ -0,0 +1,48 @@
+import json
+from datetime import datetime
+from pathlib import Path
+
+from loguru import logger
+
+from ...l1.schema import Opinion
+
+_DEFAULT_DIR = Path.home() / ".taskforce" / "logs"
+
+
+class SessionLogger:
+    def __init__(self, log_dir: Path | None = None):
+        self.log_dir = log_dir or _DEFAULT_DIR
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def log(self, agenda: str, context: str, opinions: list[Opinion], summarizer_output: str = "") -> Path:
+        timestamp = datetime.now().strftime("%Y-%m-%dT%H-%M-%S")
+        filepath = self.log_dir / f"{timestamp}.jsonl"
+
+        with open(filepath, "a", encoding="utf-8") as f:
+            # 의제 기록
+            f.write(json.dumps({
+                "type": "request",
+                "timestamp": timestamp,
+                "agenda": agenda,
+                "context": context,
+            }, ensure_ascii=False) + "\n")
+
+            # 각 패널 응답 기록
+            for op in opinions:
+                f.write(json.dumps({
+                    "type": "opinion",
+                    "model_name": op.model_name,
+                    "content": op.content,
+                    "tokens": op.tokens,
+                    "cost": op.cost,
+                }, ensure_ascii=False) + "\n")
+
+            # summarizer 출력 기록
+            if summarizer_output:
+                f.write(json.dumps({
+                    "type": "summarizer",
+                    "content": summarizer_output,
+                }, ensure_ascii=False) + "\n")
+
+        logger.debug(f"세션 로그 기록: {filepath}")
+        return filepath

taskforce/l3/__init__.py

@@ -0,0 +1,3 @@
+from .roundtable import Roundtable
+
+__all__ = ['Roundtable']

taskforce/l3/for-agent-layerinfo-l3.md

@@ -0,0 +1,7 @@
+# l3
+
+## roundtable
+Roundtable.__init__(panelists: list[Panelist], summarizer: Panelist)
+Roundtable.gather(agenda: str, context: str = "") -> list[Opinion]
+Roundtable.summarize(agenda: str, opinions: list[Opinion]) -> IdeaPool
+Roundtable.discuss(agenda: str, context: str = "") -> IdeaPool

taskforce/l3/roundtable/__init__.py

@@ -0,0 +1,3 @@
+from .roundtable import Roundtable
+
+__all__ = ['Roundtable']

taskforce/l3/roundtable/for-agent-moduleinfo.md

@@ -0,0 +1,30 @@
+# Roundtable
+
+병렬 패널 질의 + summarizer 분류 취합.
+
+## Roundtable
+
+다수 패널리스트에 의제를 병렬 질의하고 summarizer로 분류.
+
+### Properties
+panelists: list[Panelist]  # 패널 모델 목록
+summarizer: Panelist       # 분류 취합용 모델
+
+### __init__
+__init__(panelists: list[Panelist], summarizer: Panelist)
+    패널과 summarizer 설정.
+
+### Methods
+
+gather(agenda: str, context: str = "") -> list[Opinion]
+    asyncio.gather로 전체 패널 병렬 질의.
+    실패한 패널은 제외, 성공분만 반환.
+
+summarize(agenda: str, opinions: list[Opinion]) -> IdeaPool
+    raise ValueError
+    opinions를 summarizer에 전달하여 common/divergent/unique 분류.
+    JSON 파싱 실패 시 ValueError.
+
+discuss(agenda: str, context: str = "") -> IdeaPool
+    gather + summarize 일괄 실행.
+    의견 0개이면 빈 IdeaPool 반환.

taskforce/l3/roundtable/roundtable.py

@@ -0,0 +1,102 @@
+import asyncio
+import json
+import re
+
+from loguru import logger
+
+from ...l1.schema import Opinion, IdeaPool, DivergentPoint, UniquePoint
+from ...l2.panelist import Panelist
+
+_PANEL_SYSTEM_MSG = (
+    "You are an expert providing your independent analysis. "
+    "Be specific, thorough, and present your unique perspective."
+)
+
+_SUMMARIZER_SYSTEM_MSG = (
+    "You are an analyst. Given multiple expert opinions on an agenda, "
+    "classify the key points into three categories.\n"
+    "Respond ONLY in valid JSON with this exact structure:\n"
+    "{\n"
+    '  "common": ["point shared by most experts", ...],\n'
+    '  "divergent": [{"topic": "topic", "positions": {"Expert1": "position", "Expert2": "position"}}, ...],\n'
+    '  "unique": [{"point": "insight", "source_model": "ExpertName"}, ...]\n'
+    "}\n"
+    "Rules:\n"
+    "- common: points that 2+ experts agree on\n"
+    "- divergent: topics where experts have clearly different positions\n"
+    "- unique: points raised by only one expert\n"
+    "- Be thorough, do not lose information\n"
+    "- Respond in the same language as the opinions"
+)
+
+
+class Roundtable:
+    def __init__(self, panelists: list[Panelist], summarizer: Panelist):
+        self.panelists = panelists
+        self.summarizer = summarizer
+        logger.info(f"Roundtable 구성: 패널 {len(panelists)}명")
+
+    async def gather(self, agenda: str, context: str = "") -> list[Opinion]:
+        prompt = self._build_prompt(agenda, context)
+        tasks = [p.ask_async(prompt, _PANEL_SYSTEM_MSG) for p in self.panelists]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        opinions = []
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                name = self.panelists[i].model_entry.display_name
+                logger.warning(f"패널 {name} 실패, 제외: {result}")
+                continue
+            opinions.append(result)
+
+        logger.info(f"의견 수집: {len(opinions)}/{len(self.panelists)}")
+        return opinions
+
+    async def summarize(self, agenda: str, opinions: list[Opinion]) -> IdeaPool:
+        opinions_text = "\n\n".join(
+            f"--- {op.model_name} ---\n{op.content}" for op in opinions
+        )
+        prompt = f"Agenda: {agenda}\n\nExpert Opinions:\n{opinions_text}"
+
+        result = await self.summarizer.ask_async(prompt, _SUMMARIZER_SYSTEM_MSG)
+        parsed = self._extract_json(result.content)
+
+        # 비용 합산: 패널 + summarizer
+        total_cost = sum(op.cost for op in opinions) + result.cost
+        total_tokens = sum(op.tokens for op in opinions) + result.tokens
+
+        return IdeaPool(
+            agenda=agenda,
+            common=parsed.get("common", []),
+            divergent=[DivergentPoint(**d) for d in parsed.get("divergent", [])],
+            unique=[UniquePoint(**u) for u in parsed.get("unique", [])],
+            total_cost=total_cost,
+            total_tokens=total_tokens,
+        )
+
+    async def discuss(self, agenda: str, context: str = "") -> tuple[IdeaPool, list[Opinion]]:
+        opinions = await self.gather(agenda, context)
+        if not opinions:
+            logger.warning("수집된 의견 없음")
+            pool = IdeaPool(agenda=agenda, common=[], divergent=[], unique=[])
+            return pool, []
+        pool = await self.summarize(agenda, opinions)
+        return pool, opinions
+
+    def _build_prompt(self, agenda: str, context: str = "") -> str:
+        parts = [f"Agenda: {agenda}"]
+        if context:
+            parts.insert(0, f"Context: {context}")
+        return "\n\n".join(parts)
+
+    def _extract_json(self, text: str) -> dict:
+        match = re.search(r"```(?:json)?\s*([\s\S]*?)```", text)
+        if match:
+            text = match.group(1)
+
+        start = text.find("{")
+        end = text.rfind("}")
+        if start == -1 or end == -1:
+            raise ValueError(f"JSON 파싱 실패: {text[:200]}")
+
+        return json.loads(text[start:end + 1])

taskforce/l4/__init__.py

@@ -0,0 +1,3 @@
+from .taskforce_facade import Taskforce
+
+__all__ = ['Taskforce']

taskforce/l4/for-agent-layerinfo-l4.md

@@ -0,0 +1,6 @@
+# l4
+
+## taskforce_facade
+Taskforce.__init__(caller_provider: str, dotenv_path: str | None = None)
+Taskforce.discuss_async(agenda: str, context: str = "") -> IdeaPool
+Taskforce.discuss(agenda: str, context: str = "") -> IdeaPool

taskforce/l4/taskforce_facade/__init__.py

@@ -0,0 +1,3 @@
+from .taskforce_facade import Taskforce
+
+__all__ = ['Taskforce']

taskforce/l4/taskforce_facade/for-agent-moduleinfo.md

@@ -0,0 +1,25 @@
+# Taskforce Facade
+
+최상위 진입점. 초기화와 discuss 호출을 단순화.
+
+## Taskforce
+
+EnvConfig + Roundtable 조합을 단일 인터페이스로 노출.
+
+### Properties
+config: EnvConfig          # 환경 설정
+roundtable: Roundtable     # 라운드테이블 인스턴스
+
+### __init__
+__init__(caller_provider: str, dotenv_path: str | None = None)
+    raise ValueError
+    EnvConfig 로드, Panelist/Roundtable 자동 구성.
+    EnvConfig 실패 시 ValueError 전파.
+
+### Methods
+
+discuss_async(agenda: str, context: str = "") -> IdeaPool
+    async 버전. roundtable.discuss 위임.
+
+discuss(agenda: str, context: str = "") -> IdeaPool
+    sync 버전. asyncio.run으로 discuss_async 실행.

taskforce/l4/taskforce_facade/taskforce_facade.py

@@ -0,0 +1,40 @@
+import asyncio
+
+from loguru import logger
+
+from ...l1.schema import IdeaPool
+from ...l2.config import EnvConfig
+from ...l2.panelist import Panelist
+from ...l2.session_logger import SessionLogger
+from ...l2.cost_logger import CostLogger
+from ...l3.roundtable import Roundtable
+
+
+class Taskforce:
+    def __init__(self, caller_provider: str, dotenv_path: str | None = None):
+        self.config = EnvConfig(caller_provider, dotenv_path)
+
+        panelists = [Panelist(m) for m in self.config.get_active_panels()]
+        summarizer = Panelist(self.config.summarizer_model)
+        self.roundtable = Roundtable(panelists, summarizer)
+
+        self.session_logger = SessionLogger()
+        self.cost_logger = CostLogger()
+
+        logger.info("Taskforce 초기화 완료")
+
+    async def discuss_async(self, agenda: str, context: str = "") -> IdeaPool:
+        pool, opinions = await self.roundtable.discuss(agenda, context)
+
+        # 로그 기록
+        if opinions:
+            summarizer_cost = pool.total_cost - sum(op.cost for op in opinions)
+            summarizer_tokens = pool.total_tokens - sum(op.tokens for op in opinions)
+
+            self.session_logger.log(agenda, context, opinions)
+            self.cost_logger.log(agenda, opinions, summarizer_cost, summarizer_tokens)
+
+        return pool
+
+    def discuss(self, agenda: str, context: str = "") -> IdeaPool:
+        return asyncio.run(self.discuss_async(agenda, context))

taskforce/mcp_wrapper/__init__.py

@@ -0,0 +1,3 @@
+from .mcp_wrapper import mcp
+
+__all__ = ['mcp']

taskforce/mcp_wrapper/__main__.py

@@ -0,0 +1,3 @@
+from .mcp_wrapper import mcp
+
+mcp.run()

taskforce/mcp_wrapper/mcp_wrapper.py

@@ -0,0 +1,48 @@
+import os
+
+from mcp.server.fastmcp import FastMCP
+
+from ..l4.taskforce_facade import Taskforce
+
+mcp = FastMCP("taskforce")
+
+_tf = None
+
+
+def _get_taskforce() -> Taskforce:
+    global _tf
+    if _tf is None:
+        caller = os.getenv("TASKFORCE_CALLER_PROVIDER", "anthropic")
+        _tf = Taskforce(caller_provider=caller)
+    return _tf
+
+
+@mcp.tool()
+async def roundtable_discuss(agenda: str, context: str = "") -> str:
+    """Roundtable: 다수의 최고 성능 LLM(GPT, Grok, Claude, Gemini)에
+    동일 의제를 독립적으로 질의하고, 수집된 의견을 common/divergent/unique로
+    분류하여 구조화된 JSON을 반환한다.
+
+    유료 API를 호출하는 도구이다. 사용 전 반드시 사용자에게 의견을 묻고,
+    사용자가 동의한 경우에만 호출하라.
+
+    서로 다른 방식으로 발달한 모델들의 관점 다양성을 활용하여
+    robust한 아이디어 풀을 구축하는 것이 목적이다.
+    일회성 외부 의견 수집 도구이므로, 양질의 결과를 위해
+    agenda와 context를 최대한 풍부하게 제공해야 한다.
+
+    [agenda 작성 가이드]
+    - 분석/검토/비교를 요청하는 명확한 질문 형태로 작성
+    - 검토 범위와 판단 기준을 명시
+    - 모호한 표현 대신 구체적인 용어 사용
+
+    [context 작성 가이드 - 풍부할수록 좋다]
+    input 토큰은 저렴하므로 관련 정보를 아끼지 말고 최대한 제공하라.
+    패널이 충분한 맥락 없이 일반론만 답하면 가치가 없다.
+    구체적 사양, 수치, 제약 조건, 배경 지식, 도메인 맥락,
+    이미 결정된 사항, 실무적 제약 등
+    판단에 영향을 줄 수 있는 모든 정보를 포함하라.
+    """
+    tf = _get_taskforce()
+    pool = await tf.discuss_async(agenda, context)
+    return pool.model_dump_json(indent=2)