# SDK API リファレンス

agenticstar-platform SDK（v0.5.40）の全モジュール・クラス・メソッドの完全仕様です。

## インストール

pip を使用して SDK をインストールしてください。

```bash
pip install agenticstar-platform==0.5.40
```

特定モジュールのみインストールする場合は、extras を指定してください。

| Extra          | 説明                                                   |
| -------------- | ---------------------------------------------------- |
| `[[db]]`       | PostgreSQL database support                          |
| `[[rag]]`      | RAG (embedding + vector search) support              |
| `[[storage]]`  | Cloud storage (Azure, S3, GCS) support               |
| `[[security]]` | Security (content moderation, PII detection) support |
| `[[auth]]`     | AGENTIC STAR Auth service integration                |
| `[[memory]]`   | Semantic Memory (Mem0 + Qdrant) support              |
| `[[all]]`      | 全モジュール                                               |

```bash
# RAG モジュール
pip install agenticstar-platform[rag]==0.5.40

# DB + RAG + Storage
pip install agenticstar-platform[db,rag,storage]==0.5.40

# Storage（provider 別、v0.5.28+）
pip install agenticstar-platform[storage-aws]==0.5.40

# 全モジュール
pip install agenticstar-platform[all]==0.5.40
```

---

## モジュール一覧

SDK は以下の 11 のモジュールで構成されています。

| モジュール    | 説明                                                                                                      | 主要クラス                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| events   | 非同期イベント配信システム（SSE / Webhook / DB）                                                                       | EventEmitter, StreamingEvent                                                    |
| db       | PostgreSQL 接続 + Azure AD 認証                                                                             | PostgreSQLManager, DataAccess                                                   |
| rag      | RAG（embedding + vector search via Qdrant）                                                               | EmbeddingGenerator, QdrantManager                                               |
| storage  | クラウドストレージ（Azure, S3, GCS。provider 別 extra: `storage-azure` / `storage-aws` / `storage-gcp`）             | AzureBlobStorageClient, S3StorageClient                                         |
| auth     | AGENTIC STAR 認証 API クライアント                                                                              | AgenticStarAuthClient                                                           |
| memory   | セマンティックメモリ（Mem0 + Qdrant）                                                                               | SemanticMemoryClient                                                            |
| security | コンテンツモデレーション + PII 検出                                                                                   | AzureSecurityClient, ContentSafetyValidator                                     |
| common   | 共通ユーティリティ（シークレットマスク）                                                                                    | SecretMasker                                                                    |
| metering | LLM 利用量・コスト計測（台帳記録 + 日次集計, v0.5.15+）                                                                    | UsageMeter                                                                      |
| runner   | Marketplace 互換の実行ライフサイクル（identity 検証 → 入力取得 → 実行 → 結果保存/Webhook → terminal 正確に 1 回 → cleanup, v0.5.30+） | run\_marketplace\_agent                                                         |
| audit    | 行為監査台帳（承認・ツール認可・ポリシー違反等の append-only 記録。本文は digest 化して渡す設計, v0.5.31+。alerts writer は v0.5.32+）          | ActionAudit, GatewayActionAudit, GuardrailAlertWriter, GuardrailAlertAggregates |

---

## events イベントモジュール

非同期イベント配信システム。EventEmitter でイベントを発行し、SSE / Webhook / DB に配信します。

### 列挙型

#### EventType

フロントエンド UI に表示されるイベントタイプ。各メンバーをどう実装すれば表示されるかは[イベント / ストリーミングガイドの実装ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/events-guide.md#%E8%A1%A8%E7%A4%BA%E6%96%B9%E6%B3%95%E3%81%94%E3%81%A8%E3%81%AE%E5%AE%9F%E8%A3%85%E3%82%AC%E3%82%A4%E3%83%89)を参照してください。

PHASE\_START = "phase\_start"

PROGRESS\_UPDATE = "progress\_update"

THOUGHT\_MESSAGE = "thought\_message"

COMPLETION\_SUCCESS = "completion\_success"

COMPLETION\_FAILURE = "completion\_failure"

USER\_INTERACTION\_REQUIRED = "user\_interaction\_required"

UNEXPECTED\_ERROR = "unexpected\_error"

HITL\_REQUIRED\_BROWSER\_VNC = "hitl\_required\_browser\_vnc"

HITL\_REQUIRED\_BROWSER\_CLI = "hitl\_required\_browser\_cli"

HITL\_COMPLETED = "hitl\_completed"

FILE\_CREATED = "file\_created"

PERMISSION\_REQUEST = "permission\_request"

PERMISSION\_RESPONSE = "permission\_response"

TOOL\_START = "tool\_start"

TOOL\_RESULT = "tool\_result"

PROGRESS\_MESSAGE = "progress\_message"

#### SubEventType

イベントを細分化するサブイベントタイプ。`sub_event_type` だけでは表示は変わりません。表示の出し分けは [`metadata.actionType`](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/events-guide.md#subeventtype-actiontype) で指定してください。

SEARCH\_WEB = "search\_web"

COMMAND\_EXECUTION = "command\_execution"

FILE\_OPERATION = "file\_operation"

LOCAL\_ASSISTANT = "local\_assistant"

MCP\_TOOL = "mcp\_tool"

FILE\_EDITED = "file\_edited"

FILE\_READ = "file\_read"

FILE\_SEARCHED = "file\_searched"

BASH\_EXECUTED = "bash\_executed"

WEB\_FETCHED = "web\_fetched"

TASK\_LAUNCHED = "task\_launched"

TODO\_UPDATED = "todo\_updated"

VIDEO\_GENERATED = "video\_generated"

IMAGE\_GENERATED = "image\_generated"

SLIDE\_CREATED = "slide\_created"

MACOS\_AUTOMATION = "macos\_automation"

### データクラス

#### StreamingEvent

リアルタイム SSE 配信用のイベントデータ。

```python
@dataclass
class StreamingEvent:
  event_type: EventType
  execution_id: str
  message: str
  timestamp: float
  metadata: Optional[Dict[str, Any]]= None
  sub_event_type: Optional[SubEventType]= None

  def to_dict() -> Dict[str, Any]: ...
```

#### SequencedEvent

順序保証付きイベント。

```python
@dataclass
class SequencedEvent:
  sequence: int           # 0以上
  event_type: EventType
  execution_id: str
  message: str
  timestamp: float
  metadata: Optional[Dict[str, Any]]= None
  sub_event_type: Optional[SubEventType]= None

  def __post_init__(): ...  # sequence >= 0 を検証
  def to_streaming_event() -> StreamingEvent: ...
  def to_dict() -> Dict[str, Any]: ...
```

#### ExecutionMessage

マーケットプレイス UI 統合用のデータベース格納メッセージ。

```python
@dataclass
class ExecutionMessage:
  user_id: str
  conversation_id: str
  message_id: str
  chunk_type: str
  content_data: Dict[str, Any]

  def to_dict() -> Dict[str, Any]: ...
  @classmethod
  def from_streaming_event(
      event: StreamingEvent,
      user_id: str,
      conversation_id: str,
      message_id: str,
      chunk_type: Optional[str]= None
  ) -> ExecutionMessage: ...
```

### クラス

#### EventEmitter

非同期イベントキュー。イベント発行・消費を非ブロッキングで実行。

```python
class EventEmitter:
  def __init__(
      execution_id: str,
      handler: Optional[EventHandler]= None
  ): ...

  @property
  def is_completed() -> bool: ...

  @property
  def sequence_number() -> int: ...

  async def emit_event(
      event_type: EventType,
      message: str,
      metadata: Optional[Dict[str, Any]]= None,
      sub_event_type: Optional[SubEventType]= None
  ) -> None: ...

  async def emit(
      event_type: EventType,
      message: str,
      metadata: Optional[Dict[str, Any]]= None,
      sub_event_type: Optional[SubEventType]= None
  ) -> None: ...

  async def consume_events(
      timeout: float = 0.1
  ) -> AsyncGenerator[str,None]: ...

  async def drain(
      timeout: float = 0.1
  ) -> None: ...

  def mark_completed() -> None: ...

  async def cleanup() -> None: ...
```

Returns

emit\_event() → Noneイベントをキューに追加。ハンドラーが設定されている場合は非同期で呼び出される

emit() → Noneemit\_event() のエイリアス（短縮形）

consume\_events() → AsyncGenerator\[str, None]SSE フォーマットの文字列を非同期に yield。完了時に自動停止

drain() → None登録ハンドラーを駆動してキューを消費（SSE を yield しない用途向け）。内部で consume\_events() を回し、完了イベント後に自動終了

```python
from agenticstar_platform import EventEmitter, EventType

emitter = EventEmitter(execution_id="exec-abc-123")

# イベント発行
await emitter.emit_event(
    event_type=EventType.PHASE_START,
    message="ドキュメント分析を開始します",
    metadata={"phase": "analysis", "total_pages": 42}
)

# イベント消費（SSE ストリーミング）
async for chunk in emitter.consume_events():
    print(chunk)
```

#### DatabaseEventHandler

PostgreSQL の execution\_messages テーブルにイベントを永続化。

```python
class DatabaseEventHandler:
  def __init__(
      data_access: Any,
      user_id: str,
      conversation_id: str,
      message_id: str,
      table_name: str = "execution_messages",
      chunk_type_map: Optional[Dict[EventType, str]]= None
  ): ...

  async def __call__(event: StreamingEvent) -> Optional[str]: ...
```

#### WebhookEventHandler

HTTP webhook エンドポイントにイベントを送信。

```python
class WebhookEventHandler:
  def __init__(
      webhook_url: str,
      conversation_id: str,
      message_id: str,
      headers: Optional[Dict[str, str]]= None,
      timeout_seconds: int = 30,
      message_type: str = "append_message",
      token_provider: Optional[Callable[[], Optional[str]]]= None,
      chunk_type_map: Optional[Dict[EventType, str]]= None,
      request_source: Optional[str]= None
  ): ...

  async def __call__(event: StreamingEvent) -> Optional[str]: ...
```

#### CompositeEventHandler

複数の EventHandler を並列実行。

```python
class CompositeEventHandler:
  def __init__(
      handlers: List[Callable],
      return_first_chunk: bool = True
  ): ...

  async def __call__(event: StreamingEvent) -> Optional[str]: ...
```

### ファクトリ関数

```python
def create_sse_handler() -> EventHandler
```

SSE (Server-Sent Events) 形式のハンドラーを作成。

```python
def create_json_handler() -> EventHandler
```

JSON 形式のハンドラーを作成。

```python
def create_marketplace_handler(
  data_access: Any,
  webhook_url: str,
  user_id: str,
  conversation_id: str,
  message_id: str,
  token_provider: Optional[Callable[[], Optional[str]]]= None,
  request_source: Optional[str]= None
) -> CompositeEventHandler
```

マーケットプレイス UI 用の複合ハンドラー（DB + Webhook）を作成。

### プロトコル

#### EventHandler

イベント処理の汎用インターフェース。

```python
class EventHandler(Protocol):
  async def __call__(
      self, event: StreamingEvent
  ) -> Optional[str]: ...
```

Related

[データベースモジュール](#-データベースモジュール) —

<!-- -->

DatabaseEventHandler の data\_access に DataAccess を渡して永続化\
[ストレージモジュール](#-ストレージモジュール) —

<!-- -->

イベントログのクラウドストレージへのアーカイブ

---

## db データベースモジュール

PostgreSQL 接続プール + Azure AD 認証。

### 設定

#### AzureADConfig

Azure Active Directory 認証設定。

```python
@dataclass
class AzureADConfig:
  tenant_id: str
  client_id: str
  client_secret: str  # 非表示
  username: str = ""

  @classmethod
  def from_dict(data: Dict[str, Any]) -> AzureADConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "azure_ad") -> AzureADConfig: ...
```

#### PostgreSQLConfig

PostgreSQL 接続設定（Azure AD サポート）。

```python
class PostgreSQLConfig:
  provider: str = "postgresql"
  host: str = "localhost"
  port: int = 5432
  database: str = "agenticstar_db"
  use_azure_ad: bool = False
  username: Optional[str]= None
  password: Optional[str]= None  # 非表示
  pool_min_size: int = 5
  pool_max_size: int = 20
  command_timeout: int = 60
  pool_timeout: Optional[int]= 30
  max_overflow: Optional[int]= 10
  azure_ad: Optional[AzureADConfig]= None
  api_url: Optional[str]= None
  ssl_mode: str = "require"

  @classmethod
  def from_dict(data: Dict[str, Any]) -> PostgreSQLConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "database") -> PostgreSQLConfig: ...

  @classmethod
  def from_env(prefix: str = "DB_") -> PostgreSQLConfig: ...
```

**TOML 設定例:**

```toml
[database]
provider = "postgresql"
host = "db.example.com"
port = 5432
database = "agenticstar_db"
use_azure_ad = true
pool_min_size = 5
pool_max_size = 20
command_timeout = 60

[azure_ad]
tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
client_id = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
client_secret = "your-secret-here"
username = "dbuser@example.onmicrosoft.com"
```

### 接続管理

#### PostgreSQLManager

非同期 PostgreSQL 接続プール（Azure AD トークン管理対応）。

```python
class PostgreSQLManager:
  def __init__(config: PostgreSQLConfig): ...

  @property
  def config() -> PostgreSQLConfig: ...

  @property
  def pool() -> Optional[asyncpg.Pool]: ...

  async def __aenter__() -> PostgreSQLManager: ...
  async def __aexit__(...) -> None: ...

  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def close() -> None: ...

  async def execute_query(
      query: str,
      params: tuple = ()
  ) -> Dict[str, Any]: ...

  async def fetch_one(
      query: str,
      params: tuple = ()
  ) -> Optional[Dict[str, Any]]: ...

  async def fetch_all(
      query: str,
      params: tuple = ()
  ) -> List[Dict[str, Any]]: ...

  async def execute(
      query: str,
      params: tuple = ()
  ) -> str: ...
```

Returns

execute\_query() → Dict\[str, Any]{"success": bool, "data": list（SELECT / RETURNING 時の行リスト）または {"result": str}（その他 DML 時の PostgreSQL ステータス）}

fetch\_one() → Optional\[Dict\[str, Any]]1行の結果辞書、または該当なしで None

fetch\_all() → List\[Dict\[str, Any]]結果行のリスト（0件の場合は空リスト）

execute() → strPostgreSQL のステータス文字列（例: "INSERT 0 1"）

✓

Context manager 対応: `async with PostgreSQLManager(config) as mgr:`

```python
from agenticstar_platform.db import PostgreSQLConfig, PostgreSQLManager

config = PostgreSQLConfig.from_toml("config.toml")

async with PostgreSQLManager(config) as mgr:
    await mgr.initialize()

    # SELECT クエリ
    result = await mgr.fetch_all(
        "SELECT * FROM conversations WHERE user_id = $1",
        ("user-123",)
    )

    # INSERT
    await mgr.execute(
        "INSERT INTO events (event_type, data) VALUES ($1, $2)",
        ("phase_start", '{}')
    )
```

### データアクセス層

#### DataAccess

SQL インジェクション防止を備えた汎用テーブル操作ラッパー。

```python
class DataAccess:
  def __init__(
      db: PostgreSQLManager| ApiPostgreSQLManager
  ): ...

  async def __aenter__() -> DataAccess: ...
  async def __aexit__(...) -> None: ...

  async def initialize() -> None: ...
  async def close() -> None: ...

  def is_initialized() -> bool: ...
  async def ensure_initialized() -> None: ...

  async def execute_query(
      query: str,
      params: tuple = ()
  ) -> Dict[str, Any]: ...

  async def insert(
      table: str,
      data: Dict[str, Any],
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...

  async def upsert(
      table: str,
      data: Dict[str, Any],
      conflict_columns: List[str],
      update_columns: Optional[List[str]]= None,
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...

  async def select(
      table: str,
      columns: Optional[List[str]]= None,
      where: Optional[Dict[str, Any]]= None,
      order_by: Optional[str]= None,
      limit: Optional[int]= None
  ) -> Dict[str, Any]: ...

  async def select_one(
      table: str,
      columns: Optional[List[str]]= None,
      where: Optional[Dict[str, Any]]= None
  ) -> Optional[Dict[str, Any]]: ...

  async def update(
      table: str,
      data: Dict[str, Any],
      where: Dict[str, Any],
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...

  async def delete(
      table: str,
      where: Dict[str, Any],
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...
```

Returns

insert() / upsert() → Dict\[str, Any]{"success": bool, "data": list または {"result": str}}。returning 指定時はカラム値の行リスト、未指定時は {"result": str}

select() → Dict\[str, Any]{"success": bool, "data": list}

update() / delete() → Dict\[str, Any]{"success": bool, "data": {"result": str}}。returning 指定時は行リスト

主要メソッドの使用例:

```python
# INSERT
result = await da.insert("users", {"name": "Alice"}, returning=["id"])

# UPSERT（競合時は更新）
result = await da.upsert("users", {"email": "a@example.com", "name": "Alice"}, conflict_columns=["email"])

# SELECT with WHERE + ORDER + LIMIT
result = await da.select("users", columns=["id", "name"], where={"active": True}, order_by="created_at DESC", limit=10)
```

#### ConfigAccess

エージェント・ツール・ガードレール・MCP などの設定情報へのアクセス層。

```python
class ConfigAccess:
  def __init__(db: DataAccess): ...

  async def get_agent_instructions(agent_type: str) -> Dict[str, Any]: ...
  async def get_all_agent_configs() -> Dict[str, Any]: ...
  async def get_agent_config(agent_type: str, requested_level: str = "default") -> Dict[str, Any]: ...
  async def get_tool_config(tool_name: str) -> Dict[str, Any]: ...
  async def get_all_tool_configs() -> Dict[str, Any]: ...
  async def get_banned_urls() -> Dict[str, Any]: ...
  async def get_guardrails_settings() -> Dict[str, Any]: ...
  async def get_system_settings() -> Dict[str, Any]: ...
  async def get_mcp_configurations(execution_mode: Optional[str]= None) -> Dict[str, Any]: ...
```

> **禁止 URL の制限粒度を拡張する**
>
> `get_banned_urls()` は管理画面で登録された「禁止 URL」一覧を取得します。基本機能（ExtAuth Service）はドメイン単位の制限ですが、本メソッドで取得したパターンをエージェントのツール内で `re.search` 等により URL 文字列に照合することで、**URL（パス）単位の制限**を拡張機能として実装できます。設定は管理画面で一元管理されるため、運用上の重複は発生しません。

> **PII のマスクが効く範囲**
>
> `get_guardrails_settings()` の `pii_masking_enabled` は、管理コンソールの PII マスキングのスイッチの値を返すだけです。マスクは、この値を読んでマスクする Agent にだけ効きます（マーケットプレイスの実行基盤はマスクしません）。

#### ExecutionAccess

実行メッセージの取得層。

```python
class ExecutionAccess:
  def __init__(db: DataAccess): ...

  async def get_messages(
      execution_id: str
  ) -> Optional[List[Dict[str, Any]]]: ...
```

#### TelemetryAccess

NIST 監査テレメトリの保存・取得層。

```python
class TelemetryAccess:
  def __init__(db: DataAccess): ...

  async def save_telemetry(
      telemetry_data: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  async def list_telemetry(
      conversation_id: Optional[str]= None,
      service: Optional[str]= None,
      limit: int = 100,
      offset: int = 0
  ) -> Dict[str, Any]: ...

  async def get_telemetry(
      telemetry_id: str
  ) -> Optional[Dict[str, Any]]: ...
```

#### PodRuntime

Pod ライフサイクル管理（開始通知・終了通知・任意の自己スケールダウン）。

```python
class PodRuntime:
  def __init__(
      db: DataAccess,
      execution_id: str,
      pod_name: str,
      scale_down_callback: Optional[Callable[[str], Awaitable[None]]] = None
  ): ...

  async def start() -> Dict[str, Any]: ...
  async def final(status: str = "completed") -> Dict[str, Any]: ...
```

`scale_down_callback` は Pod 終了時に呼び出される自己スケールダウンハンドラ（`async def (execution_id: str) -> None`）。未指定の場合、`final()` は状態更新のみを行い、自己スケールダウンは実行しない。Pod を自身で終了（この実行の SandboxClaim を削除するなど）させたい場合に注入する。

#### ApiPostgreSQLManager

HTTP API プロキシ経由の PostgreSQL アクセス（CLI モード用）。`PostgreSQLManager` と同一の非同期インターフェースを持つ。

```python
class ApiPostgreSQLManager:
  def __init__(config: PostgreSQLConfig,*, token_provider: Callable[[], Optional[str]]): ...

  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def close() -> None: ...

  async def fetch_one(query: str, params: tuple = ()) -> Optional[Dict[str, Any]]: ...
  async def fetch_all(query: str, params: tuple = ()) -> List[Dict[str, Any]]: ...
  async def execute(query: str, params: tuple = ()) -> str: ...
  async def execute_query(query: str, params: tuple = ()) -> Dict[str, Any]: ...
```

### ファクトリ関数

```python
def create_postgresql_manager(
  config: PostgreSQLConfig
) -> Union[PostgreSQLManager, ApiPostgreSQLManager]
```

`config.api_url` の有無に応じて `PostgreSQLManager`（直接接続）または `ApiPostgreSQLManager`（API プロキシ）を自動選択して返す。

### エラー処理

データベース操作の例外処理。

```python
from agenticstar_platform.db import PostgreSQLConfig, PostgreSQLManager, DataAccess

config = PostgreSQLConfig.from_toml("config.toml")

try:
    db_manager = PostgreSQLManager(config)
    da = DataAccess(db_manager)
    await da.initialize()

    result = await da.select("users", where={"id": "user-123"})
    if result["success"] and result["data"]:
        print(f"User: {result['data'][0]['username']}")
except Exception as e:
    print(f"Database error: {e}")
finally:
    await da.close()
```

Related

[イベントモジュール](#-イベントモジュール) —

<!-- -->

DatabaseEventHandler でイベントを DB に永続化\
[RAG モジュール](#-rag-モジュール) —

<!-- -->

DB から取得したデータを Embedding 化して検索可能にする

---

## rag RAG モジュール

RAG (Retrieval-Augmented Generation): Embedding + Vector Search via Qdrant。

### 列挙型

#### VectorStoreProvider

RAG で使用するベクトルストアプロバイダー種別。

QDRANT = "qdrant"

### 例外

```text
VectorStoreError (Exception)
├── VectorStoreConfigError
│   └── QdrantConfigError
└── VectorStoreConnectionError

EmbeddingError (Exception)
└── RateLimitExceededError
```

### データクラス

#### SearchResult

単一の検索結果。

```python
@dataclass
class SearchResult:
  point_id: str
  payload: Dict[str, Any]
  score: float
  similarity: float = 0.0
```

#### UpsertResult

Upsert 操作の結果。

```python
@dataclass
class UpsertResult:
  success: bool
  point_id: str = ""
  error: Optional[str]= None
  error_code: Optional[str]= None
```

#### SearchResponse

検索操作の結果。

```python
@dataclass
class SearchResponse:
  success: bool
  results: List[SearchResult]= field(default_factory=list)
  total_found: int = 0
  query: str = ""
  error: Optional[str]= None
  error_code: Optional[str]= None
```

### エンベッディング設定

#### EmbeddingConfig

Azure OpenAI / OpenAI 互換エンドポイントのエンベッディング設定。

`provider = "openai"`（v0.5.24+）で Azure AI inference の embed-v-4-0 等の OpenAI 互換エンドポイントに接続できます（`base_url` は `/models` まで含めて指定、`api_version` は未使用）。`model` に LiteLLM 形式のプレフィックス（`azure/...` / `openai/...`）を付けた場合は provider が自動導出され、プレフィックスはデプロイメント名から除去されます。

```python
class EmbeddingConfig:
  base_url: str
  api_key: str  # 非表示
  model: str = "text-embedding-ada-002"
  api_version: str = "2024-02-15-preview"
  max_cache_size: int = 10000
  dimensions: int = 1536
  provider: str = "azure"  # "azure" | "openai"（v0.5.24+）
  max_retries: int = 5
  base_delay: float = 1.0
  max_delay: float = 60.0

  @classmethod
  def from_dict(data: Dict[str, Any]) -> EmbeddingConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "rag.embedding") -> EmbeddingConfig: ...
```

#### EmbeddingGenerator

キャッシング機能とリトライロジック付きエンベッディング生成。

```python
class EmbeddingGenerator:
  def __init__(config: EmbeddingConfig): ...

  async def generate(text: str) -> List[float]: ...
  async def batch_generate(
      texts: List[str],
      batch_size: int = 16
  ) -> List[List[float]]: ...

  def clear_cache() -> None: ...
  def get_cache_stats() -> Dict[str, Any]: ...
```

Returns

generate() → List\[float]ベクトル（次元数は config.dimensions、デフォルト 1536）。キャッシュ済みの場合は即返却

batch\_generate() → List\[List\[float]]入力テキスト順のベクトルリスト。batch\_size 単位で API 呼び出し（デフォルト 16）

get\_cache\_stats() → Dict\[str, Any]キャッシュ統計情報（cache\_size / max\_cache\_size / cache\_utilization / model\_name）

```python
# 単一テキストの Embedding
vector = await generator.generate("Hello, world!")  # → [0.012, -0.034, ...]

# バッチ Embedding
vectors = await generator.batch_generate(["text1", "text2", "text3"])
```

### ベクトルデータベース

#### QdrantConfig

Qdrant データベース設定。

```python
class QdrantConfig:
  url: str
  collection_name: str
  vector_size: int = 1536
  distance: str = "cosine"  # cosine, euclid, dot
  on_disk_vectors: bool = False
  on_disk_payload: bool = True
  hnsw_m: int = 16
  hnsw_ef_construct: int = 256
  payload_indexes: List[PayloadIndexConfig]
  auth_token_provider: Optional[Callable[[], str]]= None
  prefer_grpc: bool = True
  check_compatibility: bool = True

  @classmethod
  def from_dict(data: Dict[str, Any]) -> QdrantConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "rag.qdrant") -> QdrantConfig: ...
```

#### PayloadIndexConfig

Payload フィールドのインデックス設定。

```python
@dataclass
class PayloadIndexConfig:
  field_name: str
  field_schema: str = "keyword"  # keyword, integer, float, bool

  @classmethod
  def from_dict(data: Dict[str, Any]) -> PayloadIndexConfig: ...
```

**TOML 設定例:**

```toml
[embedding]
provider = "openai"
model = "text-embedding-3-small"
api_key = "sk-..."
dimension = 1536

[qdrant]
host = "qdrant.example.com"
port = 6333
api_key = "your-qdrant-key"
use_ssl = true
```

#### VectorStoreClientBase

ベクトルストアクライアントの抽象基底クラス（`abc.ABC`）。

```python
class VectorStoreClientBase(ABC):
  def __init__(): ...

  async def __aenter__() -> VectorStoreClientBase: ...
  async def __aexit__(...) -> None: ...

  def is_initialized() -> bool: ...
  async def ensure_initialized() -> None: ...

  @abstractmethod
  async def initialize() -> None: ...

  @abstractmethod
  async def upsert(
      point_id: str,
      text: str,
      payload: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def batch_upsert(
      items: List[Dict[str, Any]],
      batch_size: int = 256
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def search(
      query_text: str,
      limit: int = 10,
      score_threshold: float = 0.4,
      filter_conditions: Optional[Dict[str, Any]]= None
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def delete(
      point_ids: List[str]
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def get_statistics() -> Dict[str, Any]: ...

  @abstractmethod
  async def close() -> None: ...
```

Returns

upsert() → Dict\[str, Any]{"success": bool, "data": {"id": str}}

batch\_upsert() → Dict\[str, Any]{"success": bool, "data": {"total\_upserted": int}}

search() → Dict\[str, Any]{"success": bool, "data": {"query": str, "results": List\[SearchResult], "total\_found": int, "score\_threshold": float}}

get\_statistics() → Dict\[str, Any]{"success": bool, "data": {"total\_objects": int, "vectors\_count": int, "content\_type\_breakdown": dict, "collection\_name": str, "status": str}}

基底契約の `upsert(point_id, text, payload)` は具象実装 `QdrantManager.upsert(id, content, metadata)` と引数名が異なります。

#### VectorStoreClientProtocol

ベクトルストアクライアントのプロトコル（`typing.Protocol`、`@runtime_checkable`）。

```python
@runtime_checkable
class VectorStoreClientProtocol(Protocol):
  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def ensure_initialized() -> None: ...

  async def upsert(
      point_id: str,
      text: str,
      payload: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  async def batch_upsert(
      items: List[Dict[str, Any]],
      batch_size: int = 256
  ) -> Dict[str, Any]: ...

  async def search(
      query_text: str,
      limit: int = 10,
      score_threshold: float = 0.4,
      filter_conditions: Optional[Dict[str, Any]]= None
  ) -> Dict[str, Any]: ...

  async def delete(
      point_ids: List[str]
  ) -> Dict[str, Any]: ...

  async def get_statistics() -> Dict[str, Any]: ...

  async def close() -> None: ...
```

Returns

upsert() → Dict\[str, Any]{"success": bool, "data": {"id": str}}

batch\_upsert() → Dict\[str, Any]{"success": bool, "data": {"total\_upserted": int}}

search() → Dict\[str, Any]{"success": bool, "data": {"query": str, "results": List\[SearchResult], "total\_found": int, "score\_threshold": float}}

get\_statistics() → Dict\[str, Any]{"success": bool, "data": {"total\_objects": int, "vectors\_count": int, "content\_type\_breakdown": dict, "collection\_name": str, "status": str}}

#### QdrantManager

Qdrant ベクトル検索クライアント。

```python
class QdrantManager:
  def __init__(
      config: QdrantConfig,
      embedding_generator: EmbeddingGenerator
  ): ...

  async def __aenter__() -> QdrantManager: ...
  async def __aexit__(...) -> None: ...

  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def ensure_initialized() -> None: ...

  async def upsert(
      id: str,
      content: str,
      metadata: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  async def batch_upsert(
      items: List[Dict[str, Any]],
      batch_size: int = 256
  ) -> Dict[str, Any]: ...

  async def search(
      query_text: str,
      limit: int = 10,
      score_threshold: float = 0.4,
      filter_conditions: Optional[Dict[str, Any]]= None,
      ef: Optional[int]= None
  ) -> Dict[str, Any]: ...

  async def delete(
      point_ids: List[str]
  ) -> Dict[str, Any]: ...

  async def get_statistics() -> Dict[str, Any]: ...

  async def collection_exists(
      collection_name: Optional[str]= None
  ) -> bool: ...

  async def create_payload_index(
      field_name: str,
      field_schema: str = "keyword"
  ) -> Dict[str, Any]: ...

  async def delete_collection(
      collection_name: Optional[str]= None
  ) -> Dict[str, Any]: ...

  async def close() -> None: ...
```

Returns

upsert() → Dict\[str, Any]{"success": bool, "data": {"id": str}}

batch\_upsert() → Dict\[str, Any]{"success": bool, "data": {"total\_upserted": int}}

search() → Dict\[str, Any]{"success": bool, "data": {"query": str, "results": List\[SearchResult], "total\_found": int, "score\_threshold": float}}

get\_statistics() → Dict\[str, Any]{"success": bool, "data": {"total\_objects": int, "vectors\_count": int, "content\_type\_breakdown": dict, "collection\_name": str, "status": str}}

collection\_exists() → boolコレクションが存在すれば True。\`collection\_name\` 省略時は \`config.collection\_name\` を使用

create\_payload\_index() → Dict\[str, Any]payload field にインデックスを作成。\`field\_schema\` は "keyword" / "integer" / "float" / "bool" 等

delete\_collection() → Dict\[str, Any]コレクションを削除。\`collection\_name\` 省略時は \`config.collection\_name\` を使用

✓

Context manager 対応: `async with QdrantManager(config, generator) as qdrant:`

```python
from agenticstar_platform.rag import (
    EmbeddingConfig, EmbeddingGenerator,
    QdrantConfig, QdrantManager
)

emb_config = EmbeddingConfig.from_toml("config.toml")
qd_config = QdrantConfig.from_toml("config.toml")

generator = EmbeddingGenerator(emb_config)

async with QdrantManager(qd_config, generator) as qdrant:
    # ドキュメントの追加
    await qdrant.upsert(
        id="doc-001",
        content="AGENTIC STAR は AI エージェント開発プラットフォームです",
        metadata={"source": "docs", "category": "overview"}
    )

    # セマンティック検索
    results = await qdrant.search(
        query_text="AI プラットフォームとは？",
        limit=5,
        score_threshold=0.5
    )
    for r in results["data"]:
        print(f"Score: {r['score']}, Text: {r['payload']['text']}")
```

Related

[データベースモジュール](#-データベースモジュール) —

<!-- -->

DB から取得したデータを RAG に投入\
[ストレージモジュール](#-ストレージモジュール) —

<!-- -->

ドキュメントファイルをストレージから取得して Embedding 化\
[セキュリティモジュール](#-セキュリティモジュール) —

<!-- -->

Embedding 前にコンテンツの安全性を検証

---

## storage ストレージモジュール

クラウドストレージ統合（Azure Blob Storage / AWS S3 / Google Cloud Storage）。

### 列挙型

#### StorageProvider

Cloud storage provider type.

AZURE\_BLOB = "azure\_blob"

AWS\_S3 = "aws\_s3"

GCS = "gcs"

### 例外

```text
StorageError (Exception) - Base exception
├── StorageConfigError - Configuration error
├── StorageConnectionError - Connection error
└── StorageOperationError - Operation error with error_code attribute
```

### 結果型

#### UploadResult

File upload result.

```python
@dataclass
class UploadResult:
  success: bool  # Upload succeeded
  object_name: str = ""  # Object name
  object_url: str = ""  # Object URL
  file_size: int = 0  # File size
  content_type: str = ""  # Content type
  error: Optional[str]= None  # Error message
  error_code: Optional[str]= None  # Error code
  metadata: Dict[str, Any]= field(default_factory=dict)  # Metadata
```

#### DownloadResult

File download result.

```python
@dataclass
class DownloadResult:
  success: bool  # Download succeeded
  object_name: str = ""  # Object name
  local_path: str = ""  # Local file path
  file_size: int = 0  # File size
  error: Optional[str]= None  # Error message
  error_code: Optional[str]= None  # Error code
```

#### ObjectInfo

Cloud object metadata.

```python
@dataclass
class ObjectInfo:
  name: str  # Object name
  size: int  # Object size
  last_modified: Optional[str]= None  # Last modified timestamp
  content_type: Optional[str]= None  # Content type
  metadata: Dict[str, Any]= field(default_factory=dict)  # Metadata
```

#### ListResult

List operation result.

```python
@dataclass
class ListResult:
  success: bool  # Operation succeeded
  objects: List[ObjectInfo]= field(default_factory=list)  # Objects
  count: int = 0  # Object count
  prefix: str = ""  # Search prefix
  error: Optional[str]= None  # Error message
  error_code: Optional[str]= None  # Error code
```

### 設定

#### StorageConfig

Common storage configuration (base class).

```python
class StorageConfig:
  provider: StorageProvider# Provider type
  bucket_name: str  # Bucket/container name
  enabled: bool = True  # Enabled flag
  max_file_size: int = 5*1024*1024*1024  # Max file size (5GB)
  auto_create_bucket: bool = False  # Auto-create bucket
  prefix: str = ""  # Object name prefix
  custom_domain: Optional[str]= None  # Custom domain
  connection_timeout: int = 30  # Connection timeout (seconds)
  read_timeout: int = 300  # Read timeout (seconds)
```

#### AzureBlobConfig

Azure Blob Storage configuration.

```python
class AzureBlobConfig:
  bucket_name: str  # Container name
  connection_string: str  # 非表示
  enabled: bool = True
  max_file_size: int = 5*1024*1024*1024
  auto_create_bucket: bool = False
  prefix: str = ""
  custom_domain: Optional[str]= None
  connection_timeout: int = 30
  read_timeout: int = 300
  max_block_size: int = 8*1024*1024  # Max block size (8MB)
  max_single_put_size: int = 256*1024*1024  # Max single upload (256MB)

  @classmethod
  def from_dict(data: Dict[str, Any]) -> AzureBlobConfig: ...
  @property
  def provider(self) -> StorageProvider: return StorageProvider.AZURE_BLOB
```

#### S3Config

AWS S3 configuration.

```python
class S3Config:
  bucket_name: str  # Bucket name
  aws_access_key_id: str  # 非表示
  aws_secret_access_key: str  # 非表示
  region_name: str = "us-east-1"  # AWS region
  enabled: bool = True
  max_file_size: int = 5*1024*1024*1024
  auto_create_bucket: bool = False
  prefix: str = ""
  custom_domain: Optional[str]= None
  connection_timeout: int = 30
  read_timeout: int = 300
  endpoint_url: Optional[str]= None  # S3-compatible endpoint (MinIO, etc.)

  @classmethod
  def from_dict(data: Dict[str, Any]) -> S3Config: ...
  @property
  def provider(self) -> StorageProvider: return StorageProvider.AWS_S3
```

#### GCSConfig

Google Cloud Storage configuration.

```python
class GCSConfig:
  bucket_name: str  # Bucket name
  project_id: str  # GCP project ID
  enabled: bool = True
  max_file_size: int = 5*1024*1024*1024
  auto_create_bucket: bool = False
  prefix: str = ""
  custom_domain: Optional[str]= None
  connection_timeout: int = 30
  read_timeout: int = 300
  credentials_path: Optional[str]= None  # 非表示 - Path to service account JSON
  credentials_json: Optional[str]= None  # 非表示 - Service account JSON string
  credentials_base64: Optional[str]= None  # 非表示 - Base64-encoded service account JSON

  @classmethod
  def from_dict(data: Dict[str, Any]) -> GCSConfig: ...
  @property
  def provider(self) -> StorageProvider: return StorageProvider.GCS
```

### ストレージクライアント

#### AzureBlobStorageClient

Azure Blob Storage client. Supports async context manager (`async with`).

```python
class AzureBlobStorageClient:
  def __init__(config: AzureBlobConfig): ...

  @property
  def provider(self) -> StorageProvider: return StorageProvider.AZURE_BLOB
  @property
  def container_name(self) -> str: ...

  async def ensure_bucket_exists() -> bool: ...

  async def upload_file(
      file_path: str,
      object_name: Optional[str]= None,
      prefix: Optional[str]= None,
      metadata: Optional[Dict[str, Any]]= None
  ) -> UploadResult: ...

  async def download_file(
      object_name: str,
      download_path: str
  ) -> DownloadResult: ...

  async def list_objects(
      prefix: str = "",
      max_results: Optional[int]= None
  ) -> ListResult: ...

  async def delete_object(
      object_name: str
  ) -> bool: ...

  async def object_exists(
      object_name: str
  ) -> bool: ...

  async def close() -> None: ...
```

Returns

upload\_file() → UploadResultsuccess, object\_url, file\_size, content\_type を含む

download\_file() → DownloadResultsuccess, local\_path, file\_size を含む

list\_objects() → ListResultsuccess, objects: List\[ObjectInfo], count を含む

delete\_object() → bool削除に成功したら True

#### S3StorageClient

AWS S3 storage client. Supports async context manager (`async with`).

```python
class S3StorageClient:
  def __init__(config: S3Config): ...

  @property
  def provider(self) -> StorageProvider: return StorageProvider.AWS_S3
  @property
  def bucket_name(self) -> str: ...

  async def ensure_bucket_exists() -> bool: ...

  async def upload_file(
      file_path: str,
      object_name: Optional[str]= None,
      prefix: Optional[str]= None,
      metadata: Optional[Dict[str, Any]]= None
  ) -> UploadResult: ...

  async def download_file(
      object_name: str,
      download_path: str
  ) -> DownloadResult: ...

  async def list_objects(
      prefix: str = "",
      max_results: Optional[int]= None
  ) -> ListResult: ...

  async def delete_object(
      object_name: str
  ) -> bool: ...

  async def object_exists(
      object_name: str
  ) -> bool: ...

  async def close() -> None: ...
```

#### GCSStorageClient

Google Cloud Storage client. Supports async context manager (`async with`).

```python
class GCSStorageClient:
  def __init__(config: GCSConfig): ...

  @property
  def provider(self) -> StorageProvider: return StorageProvider.GCS
  @property
  def bucket_name(self) -> str: ...

  async def ensure_bucket_exists() -> bool: ...

  async def upload_file(
      file_path: str,
      object_name: Optional[str]= None,
      prefix: Optional[str]= None,
      metadata: Optional[Dict[str, Any]]= None
  ) -> UploadResult: ...

  async def download_file(
      object_name: str,
      download_path: str
  ) -> DownloadResult: ...

  async def list_objects(
      prefix: str = "",
      max_results: Optional[int]= None
  ) -> ListResult: ...

  async def delete_object(
      object_name: str
  ) -> bool: ...

  async def object_exists(
      object_name: str
  ) -> bool: ...

  async def close() -> None: ...
```

```python
from agenticstar_platform.storage import (
    S3Config, S3StorageClient
)

config = S3Config.from_dict({
    "bucket_name": "my-bucket",
    "aws_access_key_id": "AKIA...",
    "aws_secret_access_key": "secret...",
    "region_name": "ap-northeast-1"
})

# async with によるコンテキストマネージャー
async with S3StorageClient(config) as storage:
    # ファイルアップロード
    upload_result = await storage.upload_file(
        file_path="/tmp/report.pdf",
        object_name="report.pdf",
        prefix="documents/",
        metadata={"source": "documents"}
    )
    if upload_result.success:
        print(f"URL: {upload_result.object_url}")

    # オブジェクト一覧
    list_result = await storage.list_objects(prefix="documents/")
    for obj in list_result.objects:
        print(f"{obj.name} ({obj.size} bytes)")

    # ダウンロード
    download = await storage.download_file(
        object_name="documents/report.pdf",
        download_path="/tmp/downloaded.pdf"
    )
```

```python
from agenticstar_platform.storage import (
    StorageError, StorageConfigError,
    StorageConnectionError, StorageOperationError
)

try:
    result = await storage.upload_file("/tmp/large-file.zip")
except StorageConnectionError as e:
    print(f"Connection failed: {e}")
except StorageOperationError as e:
    print(f"Operation failed: {e}, code: {e.error_code}")
except StorageError as e:
    print(f"Storage error: {e}")
```

Related

[RAG モジュール](#-rag-モジュール) —

<!-- -->

ストレージのドキュメントを取得して Embedding に投入\
[セキュリティモジュール](#-セキュリティモジュール) —

<!-- -->

アップロード前のコンテンツモデレーション

---

## auth 認証モジュール

AGENTIC STAR 認証サービス統合。ユーザー・トークン・デバイス情報を管理。

### 例外

```text
AuthError (Exception)
├── AuthConfigError
└── AuthAPIError
  ├── AuthUnauthorizedError  (401)
  ├── AuthNotFoundError      (404)
  └── AuthRateLimitError     (429)
```

### 設定

#### AgenticStarAuthConfig

AGENTIC STAR 認証 API クライアントの接続設定。

```python
class AgenticStarAuthConfig:
  base_url: str
  api_key: str  # 非表示
  auth_type: str = "bearer"
  timeout: float = 30.0
  token_provider: Optional[Callable[[], Optional[str]]]= None

  @classmethod
  def create(
      base_url: str,
      api_key: str,
      auth_type: str = "bearer",
      timeout: float = 30.0,
      token_provider: Optional[Callable[[], Optional[str]]]= None
  ) -> AgenticStarAuthConfig: ...

  @classmethod
  def from_config(config_path: Optional[Path]= None) -> AgenticStarAuthConfig: ...
```

### データモデル

#### ApiUser

認証ユーザー情報（Pydantic BaseModel）。

```python
class ApiUser(BaseModel):
  id: str
  username: Optional[str]= None
  email: Optional[str]= None
  first_name: Optional[str]= None
  last_name: Optional[str]= None
  display_name: Optional[str]= None
  email_verified: bool = False
  enabled: bool = True
  created_timestamp: Optional[int]= None
  attributes: Optional[Dict[str, Any]]= None
  organization: Optional[str]= None
  organization_label: Optional[str]= None
  job: Optional[str]= None
  job_label: Optional[str]= None
  bio: Optional[str]= None
  last_login_at: Optional[str]= None
```

#### DeviceInfo

デバイス情報。

```python
class DeviceInfo(BaseModel):
  id: Optional[str]= None
  device_code: str
  device_name: Optional[str]= None
  device_type: Optional[str]= None
  device_info: Optional[Dict[str, Any]]= None
  is_active: Optional[bool]= None
  created_at: Optional[str]= None
  last_used_at: Optional[str]= None
```

#### MCPTokenInfo

MCP トークン情報。`expires_at` は `None` が「期限なし」を表します（個人トークン (PAT) の provider ではトークン供給 API が期限を返さないため。v0.5.34+）。

```python
class MCPTokenInfo(BaseModel):
  access_token: str
  token_type: str
  expires_at: Optional[datetime]= None
  scopes: List[str]
```

#### UserPagination

ページネーション情報（`get_users()` の戻り値 `pagination`）。

```python
class UserPagination(BaseModel):
  page: int
  limit: int
  total: int
  total_pages: int
  has_next: bool
  has_previous: bool
```

#### LoginHistoryEntry

ログイン履歴エントリ（`get_user()` の戻り値 `login_history` の要素）。

```python
class LoginHistoryEntry(BaseModel):
  timestamp: int
  ip_address: str
  user_agent: str
  platform: str
  location: Optional[Dict[str, Optional[str]]]= None
  success: bool
```

#### MCPTokenError

MCP トークン取得エラー（`get_mcp_tokens()` の戻り値 `errors` の値）。`code` は `CONNECTION_NOT_FOUND` / `TOKEN_EXPIRED` / `REFRESH_FAILED` など。

```python
class MCPTokenError(BaseModel):
  code: str
  message: str
```

#### OAuthProviderName

OAuth プロバイダー名を表す型エイリアス。値は DB の `oauth_providers.service` に対応し、`get_mcp_tokens(providers=[...])` に渡す識別子および `tokens` / `errors` 辞書のキーとして使用される（例: `github`、`slack`）。

```python
OAuthProviderName = str
```

### クライアント

#### AgenticStarAuthClient

AGENTIC STAR 認証 API の HTTP クライアント。

```python
class AgenticStarAuthClient:
  def __init__(config: AgenticStarAuthConfig): ...

  async def __aenter__() -> AgenticStarAuthClient: ...
  async def __aexit__(...) -> None: ...

  async def get_users(
      page: int = 1,
      limit: int = 20,
      search: Optional[str]= None,
      is_approved: Optional[str]= None,
      job: Optional[str]= None,
      organization: Optional[str]= None,
      sort_by: Optional[str]= None,
      order: Optional[str]= None,
      include_last_login: bool = False
  ) -> GetUsersResult: ...

  async def get_user(
      user_id: str
  ) -> GetUserResult: ...

  async def get_mcp_tokens(
      user_id: str,
      providers: Optional[List[str]]= None
  ) -> GetMCPTokensResult: ...

  async def close() -> None: ...
```

Returns

get\_users() → GetUsersResultsuccess, users: List\[ApiUser], pagination: UserPagination, error, error\_code

get\_user() → GetUserResultsuccess, user: ApiUser, devices: List\[DeviceInfo], login\_history, is\_deleted, deleted\_at, deleted\_by, deletion\_reason, error, error\_code

get\_mcp\_tokens() → GetMCPTokensResultsuccess, tokens: Dict\[str, MCPTokenInfo], errors, error, error\_code

```python
# ユーザー一覧の取得（ページネーション）
result = await auth_client.get_users(page=1, limit=20)
for user in result.users:
  print(f"{user.username} ({user.email})")
```

```python
from agenticstar_platform.auth import (
    AgenticStarAuthConfig, AgenticStarAuthClient
)

config = AgenticStarAuthConfig.from_config("config.toml")

async with AgenticStarAuthClient(config) as auth_client:
    # ユーザー情報取得
    result = await auth_client.get_user("user-123")
    if result.success:
        print(f"User: {result.user.username}")

    # MCP トークン取得
    tokens = await auth_client.get_mcp_tokens(
        user_id="user-123",
        providers=["slack", "gitlab"],
    )
    for provider, token in tokens.tokens.items():
        print(f"{provider}: expires={token.expires_at}")
```

Related

[イベントモジュール](#-イベントモジュール) —

<!-- -->

WebhookEventHandler の token\_provider に認証トークンを供給\
[メモリモジュール](#-メモリモジュール) —

<!-- -->

認証済みユーザーのセマンティックメモリ管理

---

## memory メモリモジュール

セマンティックメモリ（Mem0 + Qdrant）統合。ユーザーの知識・好み・事実をベクトル検索で想起。

### 設定

#### SemanticMemoryConfig

Mem0 + Qdrant によるセマンティックメモリの設定。

```python
@dataclass
class LLMProviderConfig:
  model: str                                    # "azure_openai/gpt-4.1"
  api_key: str                                  # 非表示
  base_url: Optional[str]= None
  api_version: Optional[str]= None
  aws_access_key_id: Optional[str]= None       # Bedrock 用
  aws_secret_access_key: Optional[str]= None   # Bedrock 用
  aws_region_name: Optional[str]= None          # Bedrock 用

  @classmethod
  def from_dict(data: Dict[str, Any]) -> LLMProviderConfig: ...
  @classmethod
  def from_toml(toml_path: str, section: str) -> LLMProviderConfig: ...
  @classmethod
  def from_env(prefix: str = "LLM_") -> LLMProviderConfig: ...
```

```python
@dataclass
class SemanticMemoryConfig:
  llm_config: LLMProviderConfig
  embedder_config: LLMProviderConfig
  vector_store: Optional[Dict[str, Any]]= None
  rerank: Optional[Dict[str, Any]]= None
  custom_fact_extraction_prompt: Optional[str]= None
  custom_update_memory_prompt: Optional[str]= None

  @classmethod
  def from_dict(data: Dict[str, Any]) -> SemanticMemoryConfig: ...
  @classmethod
  def from_toml(toml_path: str, section: str = "memory") -> SemanticMemoryConfig: ...
```

#### QdrantVectorStoreConfig

Qdrant Vector Store 設定を簡潔に組み立てるヘルパー dataclass。

```python
@dataclass
class QdrantVectorStoreConfig:
  url: str
  collection_name: str
  embedding_dims: int = 1536

  def to_dict() -> Dict[str, Any]: ...

  @classmethod
  def from_dict(data: Dict[str, Any]) -> QdrantVectorStoreConfig: ...
```

#### SemanticMemoryClient

セマンティックメモリの追加・検索・削除クライアント（同期 API）。

```python
class SemanticMemoryClient:
  def __init__(config: SemanticMemoryConfig): ...

  @property
  def enabled() -> bool: ...

  # 同期メソッド（await 不要）
  def add(
      messages: List[Dict[str, str]],
      user_id: str,
      metadata: Optional[Dict[str, Any]]= None
  ) -> Dict[str, Any]: ...

  def search(
      query: str,
      user_id: str,
      limit: int = 10
  ) -> Dict[str, Any]: ...

  def get_all(
      user_id: str
  ) -> Dict[str, Any]: ...

  def delete(
      memory_id: str
  ) -> Dict[str, Any]: ...

  def delete_all(
      user_id: str
  ) -> Dict[str, Any]: ...

  # 非同期メソッド
  async def cleanup() -> None: ...
```

Returns

add() → Dict\[str, Any]Mem0 の結果辞書。messages は OpenAI 形式の \[{"role": "user", "content": "..."}]

search() → Dict\[str, Any]{"results": \[...]}。各要素に memory, score 等を含む

get\_all() → Dict\[str, Any]ユーザーの全メモリを返す

delete() / delete\_all() → Dict\[str, Any]削除結果

### 例外

```text
SemanticMemoryError (Exception)
└── SemanticMemoryConfigError
```

### ユーティリティ関数

```python
def normalize_provider(provider: str) -> str
```

プロバイダー名を正規化（エイリアス対応。例: `"Azure_OpenAI"` → `"azure"`）。

```python
def parse_model_string(model: str) -> tuple[str, str]
```

モデル文字列をプロバイダーとモデル名に分割（例: `"azure_openai/gpt-4.1"` → `("azure", "gpt-4.1")`）。

```python
def get_api_key(config: LLMProviderConfig) -> str
```

LLMProviderConfig から API キーを取得（SecretStr 対応）。

```python
def convert_llm_to_mem0(llm_config: LLMProviderConfig) -> Dict[str, Any]
```

LLMProviderConfig を Mem0 形式の LLM 設定辞書に変換。

```python
def convert_embedder_to_mem0(embedder_config: LLMProviderConfig) -> Dict[str, Any]
```

LLMProviderConfig を Mem0 形式の Embedder 設定辞書に変換。openai プロバイダ（`openai/...` モデル）で `base_url` が設定されている場合は `openai_base_url` として引き渡します（v0.5.24+。embed-v-4-0 等の OpenAI 互換エンドポイント用。未設定時は公式 api.openai.com に接続されるため注意）。v0.5.35 以前は `SemanticMemoryClient` 内部の変換経路にこの引き渡しが適用されないバグがあり、v0.5.36 で修正されました。

```python
from agenticstar_platform.memory import (
    SemanticMemoryConfig, SemanticMemoryClient
)

config = SemanticMemoryConfig.from_toml("config.toml")
memory = SemanticMemoryClient(config)

# メモリ追加（同期メソッド）
memory.add(
    messages=[
        {"role": "user", "content": "私は Python が得意です"},
        {"role": "assistant", "content": "承知しました"},
    ],
    user_id="user-123",
)

# メモリ検索（同期メソッド）
result = memory.search(query="ユーザーの技術スキルは？", user_id="user-123")
for r in result.get("results", []):
    print(f"{r['memory']}")

# クリーンアップ（非同期）
await memory.cleanup()
```

Related

[認証モジュール](#-認証モジュール) —

<!-- -->

認証済みユーザー ID をメモリの user\_id として使用\
[RAG モジュール](#-rag-モジュール) —

<!-- -->

メモリ内容を Embedding 化して類似検索を強化

---

## security セキュリティモジュール

Content Moderation（Azure / AWS / GCP）+ PII Detection。AWS の PII 検出は Bedrock Guardrails `sensitiveInformationPolicy`（多言語対応、日本語含む）または Amazon Comprehend（en/es）から選択可能（`AWSSecurityConfig.pii_service`）。

### 列挙型

#### SecurityProvider

セキュリティプロバイダー種別。

AZURE = "azure"

AWS = "aws"

GCP = "gcp"

#### ContentCategory

コンテンツモデレーション分類。

HATE = "hate"

SEXUAL = "sexual"

SELF\_HARM = "self\_harm"

VIOLENCE = "violence"

PROFANITY = "profanity"

INSULT = "insult"

THREAT = "threat"

#### PIICategory

PII（個人識別情報）分類。

PERSON\_NAME = "person\_name"

EMAIL = "email"

PHONE\_NUMBER = "phone\_number"

ADDRESS = "address"

AGE = "age"

DATE\_OF\_BIRTH = "date\_of\_birth"

NATIONAL\_ID = "national\_id"

PASSPORT\_NUMBER = "passport\_number"

DRIVERS\_LICENSE = "drivers\_license"

SOCIAL\_SECURITY = "social\_security"

TAX\_ID = "tax\_id"

CREDIT\_CARD = "credit\_card"

BANK\_ACCOUNT = "bank\_account"

SWIFT\_CODE = "swift\_code"

IBAN = "iban"

MEDICAL\_RECORD = "medical\_record"

HEALTH\_INSURANCE = "health\_insurance"

IP\_ADDRESS = "ip\_address"

MAC\_ADDRESS = "mac\_address"

URL = "url"

PASSWORD = "password"

API\_KEY = "api\_key"

AWS\_ACCESS\_KEY = "aws\_access\_key"

CONNECTION\_STRING = "connection\_string"

OTHER = "other"

### 例外

```text
SecurityError (Exception)
├── SecurityConfigError
└── SecurityAPIError (status_code, error_code)
```

### 結果型

#### ContentModerationResult

コンテンツモデレーション結果。`categories` の値は severity（0-6）。

```python
@dataclass
class ContentModerationResult:
  blocked: bool                                 # しきい値以上でTrue
  categories: Dict[ContentCategory, int]= {}   # severity 0-6
  threshold: int = 2                            # 適用しきい値
  raw_response: Dict[str, Any]= {}
  error: Optional[str]= None
  error_code: Optional[str]= None
```

#### PromptShieldResult

プロンプトインジェクション検出結果。

```python
@dataclass
class PromptShieldResult:
  attack_detected: bool
  attack_type: Optional[str]= None
  confidence: float = 0.0
  raw_response: Dict[str, Any]= {}
  error: Optional[str]= None
  error_code: Optional[str]= None
  user_prompt_attack: Optional[bool]= None   # v0.5.40+ direct(userPrompt) 経路の検知内訳
  documents_attack: Optional[bool]= None     # v0.5.40+ indirect(documents) 経路の検知内訳
```

`user_prompt_attack` / `documents_attack` は攻撃経路の内訳（v0.5.40+）。`None` は「未取得」（旧版・未評価）であり `False`（評価済み非検知）と区別されます。両方既知のとき `attack_detected == (user_prompt_attack or documents_attack)` が成り立ちます。

#### PIIEntity

検出された PII エンティティ。

```python
@dataclass
class PIIEntity:
  category: PIICategory
  text: str                    # 検出されたテキスト
  offset: int                  # テキスト内の開始位置
  length: int                  # 検出テキストの長さ
  confidence: float
  provider_category: str = ""  # プロバイダー固有のカテゴリ名
```

#### PIIDetectionResult

PII 検出結果。

```python
@dataclass
class PIIDetectionResult:
  success: bool
  masked_text: str = ""
  entities: List[PIIEntity]= []
  categories_detected: List[PIICategory]= []
  raw_response: Dict[str, Any]= {}
  error: Optional[str]= None
  error_code: Optional[str]= None
```

#### SecurityCheckResult

統合セキュリティチェック結果。

```python
@dataclass
class SecurityCheckResult:
  allowed: bool                                          # 許可/ブロック
  violations: List[str]= []                             # 違反理由リスト
  content_moderation: Optional[ContentModerationResult]= None
  prompt_shield: Optional[PromptShieldResult]= None
  pii_detection: Optional[PIIDetectionResult]= None
```

#### SanitizationResult

`ContentSafetyValidator.validate_and_sanitize()` のサニタイズ結果。`marked_content` は unsafe 判定時は空文字。

```python
@dataclass
class SanitizationResult:
  is_safe: bool
  marked_content: str = ""
  metadata: Dict[str, Any]= {}
```

### 設定

#### AzureSecurityConfig

Azure Content Safety + Language Service 接続設定。

```python
class AzureSecurityConfig:
  content_safety_endpoint: str
  content_safety_api_key: str  # 非表示
  language_endpoint: Optional[str]= None     # PII 検出用
  language_api_key: Optional[str]= None      # 非表示
  enabled: bool = True
  prompt_shield_enabled: bool = True          # Prompt Shield 有効化
  moderation_enabled: bool = True             # コンテンツモデレーション有効化
  moderation_threshold: int = 2               # severity 0-6
  pii_enabled: bool = True
  pii_confidence_threshold: float = 0.7
  pii_mask_string: str = "***"                # PII マスク文字列
  timeout: float = 30.0
```

#### AWSSecurityConfig

AWS Bedrock Guardrails / Comprehend によるセキュリティ設定。

```python
class AWSSecurityConfig:
  aws_access_key_id: str = ""   # 非表示
  aws_secret_access_key: str = ""  # 非表示
  region_name: str = "us-east-1"
  guardrail_id: str = ""
  guardrail_version: str = "DRAFT"
  pii_service: str = "bedrock_guardrails"     # PII 検出経路 ("bedrock_guardrails" / "comprehend")
  enabled: bool = False
  prompt_shield_enabled: bool = True          # Prompt Shield 有効化
  moderation_enabled: bool = True             # コンテンツモデレーション有効化
  moderation_threshold: int = 2
  pii_enabled: bool = True
  pii_confidence_threshold: float = 0.7
  pii_mask_string: str = "***"                # PII マスク文字列
  timeout: float = 30.0
```

#### GCPSecurityConfig

GCP Model Armor + DLP によるセキュリティ設定。

```python
class GCPSecurityConfig:
  project_id: str
  credentials_path: Optional[str]= None  # 非表示
  # Content Safety 経路: "model_armor"(既定) | "vertex_ai_safety"(全リージョン対応)
  content_safety_backend: str = "model_armor"
  model_armor_template: str = ""
  model_armor_region: str = ""
  # Vertex AI Safety Filters + Gemini judge (content_safety_backend="vertex_ai_safety" 時)
  vertex_ai_location: str = "global"
  vertex_harm_thresholds: Dict[str, str]= {}
  vertex_judge_model: str = "gemini-2.5-flash"
  dlp_location: str = "global"
  enabled: bool = False
  prompt_shield_enabled: bool = True          # Prompt Shield 有効化
  moderation_enabled: bool = True             # コンテンツモデレーション有効化
  moderation_threshold: int = 2
  pii_enabled: bool = True
  pii_confidence_threshold: float = 0.7
  pii_mask_string: str = "***"                # PII マスク文字列
  timeout: float = 30.0
```

#### GuardrailsConfig

`ContentSafetyValidator` のガードレール設定（マーケットプレイス顧客が管理 UI で設定する値を想定）。DB の `guardrails_settings` 辞書から `from_dict()` で生成できる。`moderation_threshold` は severity 0-6（0=無効, 2=推奨, 6=極度のみ）。

```python
@dataclass
class GuardrailsConfig:
  prompt_shield_enabled: bool = True
  moderation_threshold: int = 2
  fail_on_error: bool = True
  mark_content: bool = True

  @classmethod
  def from_dict(data: Dict[str, Any]) -> GuardrailsConfig: ...
```

### クライアント

#### SecurityClientBase

全セキュリティクライアント（Azure / AWS / GCP）の抽象基底クラス。`enabled` は設定の有効状態を反映し、`provider` はサブクラスで実装される抽象プロパティ（プロバイダー種別を返す）。

```python
class SecurityClientBase:
  @property
  def enabled() -> bool: ...

  @property
  def provider() -> SecurityProvider: ...
```

#### AzureSecurityClient

Azure Content Safety（コンテンツモデレーション）と Language Service（PII 検出）のクライアント。

```python
class AzureSecurityClient(SecurityClientBase):
  def __init__(config: AzureSecurityConfig): ...

  async def __aenter__() -> AzureSecurityClient: ...
  async def __aexit__(...) -> None: ...

  @property
  def enabled() -> bool: ...

  @property
  def provider(self) -> SecurityProvider: return SecurityProvider.AZURE

  async def check_content_moderation(
      text: str,
      threshold: Optional[int]= None
  ) -> ContentModerationResult: ...

  async def check_prompt_shield(
      user_prompt: str,
      documents: Optional[List[str]]= None
  ) -> PromptShieldResult: ...

  async def detect_pii(
      text: str,
      mask: bool = True,
      language: str = "ja",
      confidence_threshold: Optional[float]= None
  ) -> PIIDetectionResult: ...

  async def detect_pii_batch(  # v0.5.23+
      texts: List[str],
      mask: bool = True,
      language: str = "ja",
      confidence_threshold: Optional[float]= None
  ) -> List[PIIDetectionResult]: ...

  async def check_security(
      text: str,
      check_moderation: bool = True,
      check_prompt_shield: bool = True,
      check_pii: bool = False,
      fail_on_error: bool = True
  ) -> SecurityCheckResult: ...

  async def close() -> None: ...
```

Returns

check\_content\_moderation() → ContentModerationResultblocked（ブロック判定）, categories（severity 0-6）

check\_prompt\_shield() → PromptShieldResultattack\_detected, attack\_type, confidence

detect\_pii() → PIIDetectionResultsuccess, entities（PIIEntity リスト）, masked\_text

detect\_pii\_batch() → List\[PIIDetectionResult]入力と同順・同長。Azure は 5 documents/request でバッチ送信（呼び出し数最大 1/5）。429 は Retry-After 尊重で自動リトライし、枯渇継続時は error\_code="RATE\_LIMITED" でテキスト単位に fail-closed（v0.5.23+）

check\_security() → SecurityCheckResultallowed, violations, 各検出結果

```python
# PII マスク結果の利用
result = await security.detect_pii("Email: user@example.com", mask=True)
print(result.masked_text)  # → "Email: ***"
print(result.entities[0].category)  # → PIICategory.EMAIL
```

#### AWSSecurityClient / GCPSecurityClient

Azure と同一のインターフェース（`SecurityClientBase` 継承）。`check_content_moderation()`, `check_prompt_shield()`, `detect_pii()`, `check_security()`, `close()` を実装。`detect_pii_batch()` は基底クラスの逐次デフォルト実装を継承（プロバイダ側バッチ最適化は Azure のみ、v0.5.23+）。

```python
from agenticstar_platform.security import (
    AzureSecurityConfig, AzureSecurityClient
)

config = AzureSecurityConfig(
    content_safety_endpoint="https://your-cs.cognitiveservices.azure.com/",
    content_safety_api_key="your-key",
)

async with AzureSecurityClient(config) as security:
    # コンテンツモデレーション
    moderation = await security.check_content_moderation(
        text="This is a sample message",
        threshold=2,
    )

    if moderation.blocked:
        print(f"Content blocked: {moderation.categories}")

    # 統合チェック
    result = await security.check_security(
        text="Contact me at user@example.com or 123-456-7890",
        check_pii=True,
    )

    if not result.allowed:
        print(f"Violations: {result.violations}")
    if result.pii_detection and result.pii_detection.entities:
        print(f"PII found: {result.pii_detection.masked_text}")
```

#### ContentSafetyValidator

外部から取得したコンテンツ（Web / MCP など）を `SecurityClientProtocol` 実装（`AzureSecurityClient` 等）で検証し、`GuardrailsConfig` に基づいてサニタイズ・マーキングするラッパー。`validate_and_sanitize()` は単一コンテンツ、`validate_multiple()` は複数コンテンツを一括処理する。`mark_content()` / `unmark_content()` はマーカー（`[EXT:...]...[/EXT]`）を付与・除去する静的メソッド。

```python
class ContentSafetyValidator:
  def __init__(
      security_client: SecurityClientProtocol,
      guardrails: Optional[GuardrailsConfig]= None
  ): ...

  @property
  def guardrails() -> GuardrailsConfig: ...

  def update_guardrails(guardrails: GuardrailsConfig) -> None: ...

  async def validate_and_sanitize(
      content: str,
      source_type: str,
      source_url: Optional[str]= None,
      user_prompt: Optional[str]= None
  ) -> SanitizationResult: ...

  async def validate_multiple(
      contents: List[Tuple[str, str, Optional[str]]],
      user_prompt: Optional[str]= None
  ) -> Tuple[bool, List[str], List[Dict[str, Any]]]: ...

  @staticmethod
  def mark_content(
      content: str,
      source_type: str,
      source_url: Optional[str]= None
  ) -> str: ...

  @staticmethod
  def unmark_content(marked_content: str) -> Tuple[str, Optional[str], Optional[str]]: ...
```

Returns

validate\_and\_sanitize() → SanitizationResultis\_safe（安全判定）, marked\_content（マーキング済み）, metadata

validate\_multiple() → Tuple\[bool, List\[str], List\[Dict\[str, Any]]]全体の安全判定, マーキング済みコンテンツリスト, メタデータリスト

mark\_content() → strソース情報を付与したマーキング済みコンテンツ

unmark\_content() → Tuple\[str, Optional\[str], Optional\[str]]オリジナルコンテンツ, source\_type, source\_url

### ファクトリ関数

config JSON からプロバイダーを自動判別し、適切な SecurityClient を生成するモジュールレベル関数。

```python
def detect_provider(config: Dict[str, Any]) -> SecurityProvider
```

config JSON からセキュリティプロバイダー（Azure / AWS / GCP）を自動判別。判別できない場合は `SecurityConfigError`。

```python
def create_security_client(
  config: Dict[str, Any],
  pii_config: Optional[Dict[str, Any]]= None
) -> SecurityClientBase
```

config JSON から対応する SecurityClient を生成。`pii_config` を渡すと content\_safety と pii\_language の設定を統合（Azure）。

```python
def create_content_safety_client(config: Dict[str, Any]) -> SecurityClientBase
```

Content Moderation / Prompt Shield 用のショートカット。`create_security_client(config)` に委譲。

```python
def create_pii_client(config: Dict[str, Any]) -> SecurityClientBase
```

PII 検出／マスク用のショートカット。Azure では Language Service エンドポイントとして設定。

Related

[RAG モジュール](#-rag-モジュール) —

<!-- -->

Embedding 投入前のコンテンツ検証パイプライン\
[ストレージモジュール](#-ストレージモジュール) —

<!-- -->

ファイルアップロード前の PII スクリーニング\
[イベントモジュール](#-イベントモジュール) —

<!-- -->

モデレーション結果をイベントとして配信

---

## common 共通モジュール

共通ユーティリティ。SQL インジェクション防止・シークレットマスク・非同期コンテキストマネージャーミックスイン。

### SecretMasker

シークレット値（パスワード・トークン等）をキー名に基づいてマスクするユーティリティ。

```python
class SecretMasker:
  def __init__(
      secret_keys: Optional[Set[str]]= None,
      mask_string: str = "***",
      case_sensitive: bool = False,
  ): ...

  def mask_value(key: str, value: Any) -> Any: ...
  def mask_dict(data: Dict[str, Any]) -> Dict[str, Any]: ...
```

Returns

mask\_value() → Anykey がシークレットキーなら mask\_string、それ以外は元の値を返す

mask\_dict() → Dict\[str, Any]dict を再帰走査し、シークレット値をマスクした新しい dict を返す

```python
def mask_secret(value: str, visible_chars: int = 0, mask_string: str = "***") -> str
```

単一文字列をマスクするショートカット関数。

```python
from agenticstar_platform.common import SecretMasker, mask_secret

masker = SecretMasker()
safe = masker.mask_dict({
    "username": "alice",
    "password": "p@ssw0rd",
    "api_key": "sk-12345",
})
# → {"username": "alice", "password": "***", "api_key": "***"}

mask_secret("my-secret-api-key-12345")                   # → "***"
mask_secret("my-secret-api-key-12345", visible_chars=4)  # → "my-s***"
```

### validate\_identifier

テーブル名・カラム名など単一の識別子を検証するユーティリティ。SQL インジェクション対策として、英数字とアンダースコアのみを許可する。`DataAccess` 内部で自動的に使用されるが、カスタムクエリを構築する際にも直接使用できる。

```python
def validate_identifier(identifier: str, identifier_type: str = "identifier") -> str
```

Returns

str検証を通過した識別子をそのまま返す。不正な場合は IdentifierValidationError を送出

`identifier_type` はエラーメッセージ用の識別子種別ラベルで、既定値は `"identifier"`。

### validate\_identifiers

識別子（カラム名・テーブル名等）のリストを一括で検証するユーティリティ。SQL インジェクション対策として、英数字とアンダースコアのみを許可する。

```python
def validate_identifiers(identifiers: List[str], identifier_type: str = "column") -> List[str]
```

Returns

List\[str]検証を通過した識別子のリストを入力順で返す。不正な識別子が含まれる場合は IdentifierValidationError を送出

`identifier_type` は検証対象の種別を表し、既定値は `"column"`。単数版の `validate_identifier`（既定値 `"identifier"`）とは既定値が異なる点に注意。

### validate\_order\_by

ORDER BY 句を検証するユーティリティ。`column_name ASC|DESC` 形式のみ許可する。

```python
def validate_order_by(order_by: str) -> str
```

Returns

str検証を通過した ORDER BY 句をそのまま返す。不正な場合は IdentifierValidationError を送出

```python
from agenticstar_platform.common import validate_identifier, validate_order_by

table = validate_identifier("users")        # OK: "users"
validate_identifier("users; DROP TABLE --")  # → IdentifierValidationError

order = validate_order_by("created_at DESC") # OK: "created_at DESC"
```

### AsyncContextManagerMixin

非同期コンテキストマネージャーのミックスインクラス。SDK 内部で `async with` パターンを統一的に実装するために使用。

```python
class AsyncContextManagerMixin:
  async def __aenter__(self) -> Self: ...
  async def __aexit__(...) -> None: ...
  @abstractmethod
  async def close(self) -> None: ...
```

### IdentifierValidationError

`validate_identifier` / `validate_order_by` が不正な識別子に対して送出する例外。`Exception` を直接継承する。

```python
class IdentifierValidationError(Exception): ...
```

---

## エラーハンドリング

全モジュールで共通の例外処理パターンを使用します。各モジュールはモジュール固有の基底例外クラスを持ち、サブクラスで具体的なエラーを区別します。

### 例外階層一覧

```text
Exception
├── IdentifierValidationError
├── VectorStoreError
│   ├── VectorStoreConfigError
│   │   └── QdrantConfigError
│   └── VectorStoreConnectionError
├── EmbeddingError
│   └── RateLimitExceededError
├── StorageError
│   ├── StorageConfigError
│   ├── StorageConnectionError
│   └── StorageOperationError
├── AuthError
│   ├── AuthConfigError
│   └── AuthAPIError
│       ├── AuthUnauthorizedError (401)
│       ├── AuthNotFoundError (404)
│       └── AuthRateLimitError (429)
├── SemanticMemoryError
│   └── SemanticMemoryConfigError
└── SecurityError
  ├── SecurityConfigError
  └── SecurityAPIError
```

### 共通パターン

全モジュールで「具体的な例外 → 基底例外 → Exception」の順にキャッチします。

```python
from agenticstar_platform.storage import StorageError, StorageOperationError
from agenticstar_platform.auth import AuthError, AuthAPIError
from agenticstar_platform.security import SecurityError, SecurityAPIError

async def process_document(doc_id: str):
    try:
        # 1. DB からドキュメント取得
        doc = await db.fetch_one(
            "SELECT * FROM documents WHERE id = $1", (doc_id,)
        )

        # 2. セキュリティチェック
        moderation = await security.check_content_moderation(doc["content"])
        if moderation.blocked:
            raise ValueError("Content policy violation")

        # 3. Embedding 生成 + ベクトル DB に保存
        await qdrant.upsert(
            id=doc_id,
            content=doc["content"],
            metadata={"source": "documents"}
        )

        # 4. 処理結果をストレージに保存
        await storage.upload_bytes(
            data=doc["content"].encode(),
            object_name=f"processed/{doc_id}.txt"
        )

    except StorageOperationError as e:
        # ストレージ操作エラー → error_code で判断
        logger.error(f"Storage op failed: {e.error_code}")
    except AuthAPIError as e:
        # 認証 API エラー → status_code で判断
        logger.error(f"Auth failed: {e.status_code}")
    except (StorageError, AuthError, SecurityError) as e:
        # モジュール基底例外でフォールバック
        logger.error(f"Module error: {type(e).__name__}: {e}")
    except Exception as e:
        # 予期しないエラー
        logger.critical(f"Unexpected: {e}")
        raise
```

---

## metering 計測モジュール

v0.5.15+ — LLM の**利用量・コスト**を計測する純インフラ。LLM 応答/トークンからコストを算出し、**1 呼び出し = 1 行**で `llm_usage_ledger` に記録、日次集計（`llm_usage_daily`）とコスト可視化クエリを提供します。エージェントロジック非依存で、自社ホスト・マーケットプレイス BYO で同一に使えます（プロセス内記録のためヘッダ伝播は不要）。

- **コスト算出はプラガブル**: 既定は **litellm**（`completion_cost` / `cost_per_token`）を使用し、long-context / プロンプトキャッシュ / tier 価格を反映。litellm 非導入時はトークンのみ記録（`cost_usd = NULL`）。`cost_fn=` で任意エンジンに差し替え可。
- **DB**: `execute_query(query, params) -> {success, data, error}` を持つハンドル（SDK の `DataAccess` / `PostgreSQLManager`）をそのまま渡せます。

### UsageMeter

```python
from agenticstar_platform.metering import UsageMeter

meter = UsageMeter(db=data_access)                  # cost_fn=, currency= は任意
await meter.ensure_schema()                          # 台帳/集計表/集計関数を冪等作成（既存環境では不要）

# 1 LLM 呼び出しを記録（コストは自動算出・記録失敗は握り潰し安全）
await meter.record(
    model="gpt-5.5", response=resp, endpoint="chat/completions",
    labels={"execution_id": eid, "message_id": mid, "conversation_id": cid, "user_id": uid},
)

# 呼び出しをラップして自動記録
resp = await meter.track(model="gpt-5.5", labels=ids)(litellm.acompletion)(**params)

# コストのみ（記録なし）
usd = UsageMeter.cost_usd("gpt-5.5", response=resp)

# 日次集計 + コスト可視化（ダッシュボード/請求）
await meter.rollup_recent()
rows = await meter.daily_cost(by="model", since_days=30)   # by = "model" | "user" | "agent" | "day"
```

### メソッド

| メソッド                                                                                                                                                                                                          | 説明                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `UsageMeter(db, *, cost_fn=None, currency="USD")`                                                                                                                                                             | DB ハンドルとコスト関数で初期化                                                                                 |
| `UsageMeter.cost_usd(model, response=None, usage=None, cost_fn=None)`                                                                                                                                         | コスト(USD)のみ算出（static）                                                                              |
| `await ensure_schema(*, with_rollup=True)`                                                                                                                                                                    | `llm_usage_ledger` / `llm_usage_daily` / `rollup_llm_usage_daily()` を冪等作成                         |
| `await record(*, model, response=None, usage=None, endpoint=None, agent_type=None, level=None, labels=None, stream=False, success=True, request_id=None, cost_usd=None, missing_reason=None, fail_safe=True)` | 1 行記録し算出コストを返す（`missing_reason` は usage 欠落時の理由。usage 取得行は NULL 保存。v0.5.21+）                       |
| `track(*, model=None, endpoint=None, labels=None, ...)`                                                                                                                                                       | async LLM 呼び出しをラップして自動記録するデコレータ                                                                   |
| `await rollup_recent()`                                                                                                                                                                                       | 前日・当日を集計表へ反映（冪等）                                                                                  |
| `await daily_cost(*, by="model", since_days=30)`                                                                                                                                                              | 集計表からコスト内訳を取得                                                                                     |
| `default_cost_fn(model, response=None, usage=None)`                                                                                                                                                           | モジュール関数。`UsageMeter` の既定コスト算出関数（`cost_fn` 未指定時に使用）。litellm 経由でコスト(USD)を算出、算出不可時は None             |
| `extract_usage(usage)`                                                                                                                                                                                        | モジュール関数。usage オブジェクト/dict から `{"input_tokens", "output_tokens", "total_tokens"}` を抽出（取得不可時は None） |
| `round_cost_usd(v)`                                                                                                                                                                                           | モジュール関数。コスト(USD) を `Decimal`（小数点以下8桁）へ整形するユーティリティ                                                 |

`llm_usage_ledger` の既定 DDL は可搬（任意の PostgreSQL）。各行は `usage_status`（`present`/`missing`）と `missing_reason`（欠落理由・v0.5.21+）を持ち、`cost_usd IS NULL`（価格未マップ）・`usage_status='missing'`・true-zero を区別できます。大規模では月次パーティション化（pg\_partman 等）を推奨します。

---

## audit 行為監査モジュール

v0.5.31+ — エージェント実行系の**行為イベント**（承認/却下、ツール認可、ポリシー違反、キルスイッチ、外部エージェント呼び出し等）を append-only 台帳（`agent_action_audit` / `llm_gateway_action_audit`）へ記録する純インフラ。利用量・コスト（metering）とは**書き込み保証で区別**された証跡です。追加依存なし（標準ライブラリのみ・core に同梱）。

- **本文は渡さない（使用契約）**: プロンプト・ツール引数等の生値は台帳へ渡さず、`canonical_digest()`（SHA-256）で片方向化して `payload_digest` へ。**SDK は機密の自動検出・redaction は行いません**。フィールド上限（`reason` 300 字截断 / `payload_digest` は 64 桁の小文字 hex 以外を破棄 / `metadata` はキー順正規化 JSON が 2KB 超で本体破棄 = digest + サイズのみ、常に deep-copy 正規化）は誤混入時の**被害量を制限する**ガードであり、それ自体が漏洩防止ではありません。
- **書き込みモードは 3 種**: `record()` = プロセス生存中 at-least-once（bounded retry → 失敗時は `action_audit_spill` マーカー付きログ行へサニタイズ済み row を JSON 出力）／ `record_sync()` = **audit-before-act**（DB へ書けなければ `ActionAuditWriteError` — 監査に書けない承認は成立させない）／ `record_nowait()` = ホットパス用 fire-and-forget（strong ref 保持・backlog 上限 512 超過は即 spill・開始前 cancel も spill。**プロセス即死時は失われうる best-effort**）。
- **`approval.*` イベントは `actor_ref` 必須**（欠落は同期 `ValueError`）。
- **DB**: `execute_query(query, params) -> {success, data, error}` を持つハンドル（SDK の `DataAccess` / `PostgreSQLManager`）。

### ActionAudit / GatewayActionAudit

```python
from agenticstar_platform.audit import ActionAudit, GatewayActionAudit, canonical_digest

audit = ActionAudit(db=data_access, source="worker", system_version=image_tag)
await audit.ensure_schema()                       # 台帳/索引を冪等作成（既存環境では不要）

# ホットパス（ツール認可等）: fire-and-forget
audit.record_nowait(
    event_type="tool.access", actor_type="agent", decision="deny",
    resource="bash", action="execute", reason="blocked_command",
    conversation_id=cid, execution_id=eid,
    payload_digest=canonical_digest({"command": cmd}),
)

# 承認（audit-before-act）: 送出されたら行為を中断する
await audit.record_sync(
    event_type="approval.granted", actor_type="human", actor_ref=approver_id,
    decision="granted", resource=tool_name, conversation_id=cid,
)

await audit.aclose()                              # 終了時: pending を drain（timeout 分は cancel + spill）

gw = GatewayActionAudit(db=gateway_da)            # LLM Gateway ポリシー判定用（virtual key 識別）
await gw.record(event_type="policy.mcp_stripped", decision="stripped",
                virtual_key_id=vk, request_id=rid)
```

### メソッド

| メソッド                                              | 説明                                                                                                |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ActionAudit(db, *, source, system_version=None)` | `agent_action_audit` writer。`source`（`'worker'` / `'cli-api'` 等）必須                                |
| `GatewayActionAudit(db, *, system_version=None)`  | `llm_gateway_action_audit` writer（virtual key 識別）                                                 |
| `await ensure_schema()`                           | 台帳/索引を冪等作成 + `REVOKE UPDATE/DELETE`（best-effort。本番の append-only 強制は insert-only ロール分離を推奨）         |
| `await record(**fields)`                          | at-least-once 記録。DB へ書けたら `True`、spill 退避のみなら `False`（validation の `ValueError` は同期送出、cancel は伝播） |
| `await record_sync(**fields)`                     | audit-before-act 記録。DB 書き込み失敗時 `ActionAuditWriteError`（validation は `ValueError`）                 |
| `record_nowait(**fields)`                         | fire-and-forget（`asyncio.Task` を返す。close 中/backlog 超過/loop 無しは即 spill で `None`）                   |
| `await aclose(timeout=10.0)`                      | pending を drain。timeout 分は cancel され行は spill、以後の新規は即 spill                                        |
| `canonical_digest(payload)`                       | モジュール関数。任意 payload の SHA-256 digest（キー順正規化 JSON・非 JSON 型は文字列化 fallback。`None` は `None`）           |

主なフィールド: `event_type` ／ `actor_type`（推奨: `human` | `agent` | `system`。実装は非空のみ検証）／ `actor_ref`（`approval.*` は必須）／ `decision` ／ `reason` ／ `resource` ／ `action` ／ `policy_id` / `policy_version` ／ 相関キー（`execution_id` / `conversation_id` / `message_id` / `request_id`）／ `payload_digest` ／ `metadata`。各行には内容の完全性検証用に `row_hash`（SHA-256）が自動付与されます。

### GuardrailAlertWriter / GuardrailAlertAggregates（v0.5.32+）

Admin トリアージ用 `guardrail_alerts`（**非権威的**運用ビュー。権威は行為監査台帳）と、非連結日次集計 `guardrail_alert_daily_aggregates` の producer writer です。配送保証は上記 writer と同一（bounded FAF + retry → spill → `aclose()` drain）。

```python
from agenticstar_platform.audit import GuardrailAlertWriter, GuardrailAlertAggregates

alerts = GuardrailAlertWriter(db=data_access, system_version=image_tag)
await alerts.ensure_schema()                       # 行 + 集計テーブル + index + REVOKE
alerts.record_nowait(                              # confirmed block のみ。冪等 (event_key v2)
    source_surface="llm_gateway", policy_outcome="blocked",
    policy_source="llm_gateway_guardrails_settings", decision_point="input",
    request_id=rid, detection_types=["harmful_content"],
    moderation_categories={"Violence": 4},         # カテゴリ別**実測** severity (2/4/6)
)
agg = GuardrailAlertAggregates(db=data_access)
agg.record_nowait(source_surface="llm_gateway", category="SelfHarm", severity=6)
```

設計上の強制事項: 行スキーマに利用者 ID 列なし（人物特定不可）／ SelfHarm を行に載せると同期 `ValueError`（表記ゆれ・ネスト・str-Enum `.value` も検出。SelfHarm は集計のみ、集計 writer は相関 ID 引数を持たない）／ 行の `policy_outcome` は `blocked` のみ／ replay は `ON CONFLICT (event_key) DO NOTHING` で Admin の lifecycle 変更を巻き戻さない。権限は行 = producer INSERT のみ、集計 = INSERT + UPDATE(count) + SELECT(count)。集計値は at-least-once 由来の二重加算があり得る近似値（課金・規制報告に使用しない）。

v0.5.40+: `source_surface` に `agent_worker`（会話 Pod worker 面）を追加。行に `policy_category`（攻撃方式の閉語彙: `prompt_injection` / `system_prompt_extraction` / `implementation_access` / `credential_request` / `file_system_access` / `security_bypass` / `custom_policy` / `unclassified`）を追加 — 閉語彙外は同期 `ValueError`（自由文・rule 名の流入防止）で、SelfHarm 検査は `prompt_shield_origin` / `policy_category` にも適用されます。

---

## まとめ

AGENTIC STAR Platform SDK v0.5.40 は、以下の 11 の専門モジュールで構成された包括的なツールキットです:

- **Events** — 非同期イベント配信（SSE / Webhook / DB）
- **Database** — PostgreSQL + Azure AD 認証 + 専門アクセス層（Config / Execution / Telemetry / PodRuntime）
- **RAG** — Embedding + Vector Search（Qdrant）
- **Storage** — Cloud Storage（Azure / S3 / GCS）
- **Auth** — AGENTIC STAR 認証サービス統合
- **Memory** — Semantic Memory（Mem0 + Qdrant）
- **Security** — Content Moderation + PII Detection（Azure / AWS / GCP マルチクラウド対応）
- **Common** — 共通ユーティリティ（SQL インジェクション防止・シークレットマスク）
- **Metering** — LLM 利用量・コスト計測（台帳 + 日次集計, v0.5.15+）
- **Runner** — Marketplace 互換の実行ライフサイクル（`run_marketplace_agent`: identity 検証 → 入力取得 → 実行 → 結果保存/Webhook → terminal 正確に 1 回 → cleanup, v0.5.30+）
- **Audit** — 行為監査台帳（`ActionAudit` / `GatewayActionAudit`: 承認・ツール認可・ポリシー違反等の append-only 記録。本文は digest 化して渡す設計, v0.5.31+）

各モジュールは独立してインストール・利用可能であり、組み合わせることで強力な AI エージェントアプリケーションを構築できます。SDK はインフラのみを提供し、エージェントロジックは開発者が自由に設計します。
