Gateco

Gateco Python SDK

Gateco API 用の公式 Python クライアントです。AI システム向けに、権限を考慮した検索を提供します。

---

解決する課題

Gateco がない場合、従業員が AI アシスタントに「CEO の給与はいくらですか？」と尋ねると、 RAG パイプラインは漏えいした人事文書から給与を返してしまいます。

Gateco を使用すると：

from gateco_sdk import GatecoClient

client = GatecoClient("https://api.gateco.ai")
client.login("[email protected]", "...")

result = client.retrievals.execute(
    query="What is the CEO's salary?",
    principal_id="user_james_wu",
    connector_id="connector_hr_docs",
    search_mode="hybrid",
)

# result.allowed_chunks → [] (denied — James Wu lacks HR classification access)
# result.denied_count   → 1
# result.decision       → "DENIED"
# Your AI model never sees the salary data

Gateco は AI エージェントとベクトルストアの間に位置します。コンテンツがモデルに届く前に、 すべての検索に対してアクセス ポリシーに基づく評価が行われます。

---

インストール

pip install gateco

MCP サーバーのサポート（Claude Desktop、Cursor など）を利用するには：

pip install gateco[mcp]

---

認証

Gateco API キーの形式は gck_<env>_<random> です（例：gck_live_abc123...）。

ダッシュボード、または client.api_keys.create(name="my-service") からキーを生成します。

from gateco_sdk import AsyncGatecoClient, GatecoClient

# Async client with API key
client = AsyncGatecoClient("https://api.gateco.ai", api_key="gck_live_abc123...")

# Sync client with API key
client = GatecoClient("https://api.gateco.ai", api_key="gck_live_abc123...")

# Or use email/password login (issues a short-lived JWT)
client = GatecoClient("https://api.gateco.ai")
client.login("[email protected]", "password")

API キーは、すべてのリクエストで X-API-Key ヘッダーとして送信されます。CLI または MCP サーバーを使用する場合は、 GATECO_API_KEY 環境変数で設定します。このキーは保存済みのログイン情報より優先されます。

認証情報がまったくない場合：1.13.0 以降、api_key、GATECO_API_KEY、access_token を指定せずに構築されたクライアントは、 gateco login が保存したセッション（およびその base_url）を ~/.gateco/credentials.json から読み込み、 更新されたトークンを書き戻します。1 台のマシンで一度ログインすれば、CLI、MCP サーバー、自作のスクリプトで利用できます。 更新時にトークンがローテーションされ、2 つのコピーが互いを無効にしてしまうため、このファイルを別のマシンにコピーしないでください。

API キーを利用できるルート

キーには明示的なスコープが設定され、作成時に選択します（Settings > API Keys、すべてのプランが対象）。 ここに記載されていない操作には、ユーザーセッション（gateco login または client.login(...)）が必要です。 該当するルートにキーを送信すると 401 AUTH_JWT_REQUIRED が返され、必要なスコープを持たないキーには 403 API_KEY_SCOPE_MISSING が返されます。

スコープ	ルート
retrieve	POST /api/retrievals/execute、POST /api/retrievals/filter、POST /api/answers/execute、GET /api/principals、GET /api/principals/:id、POST /api/principals/resolve、GET /api/groups（2026-10-02 以降）、GET /api/connectors（id、name、type、status）
ingest	POST /api/v1/ingest、/batch、/file、/files、DELETE /api/v1/resources/:id、/api/v1/ingest/jobs*
relationships	POST、GET、DELETE /api/relationships
principals	POST、PATCH、DELETE /api/principals（ローカルディレクトリ）
任意のキー	GET /api/users/me（キーの名前とスコープを報告します）

セッションのみ：ポリシー、コネクターの作成・更新・削除とその検索および取り込み設定、ID プロバイダー、API キー管理、監査、検索履歴、課金、 アクセスシミュレーター、分類候補。

---

クイックスタート

非同期（本番サービスに推奨）

import asyncio
from gateco_sdk import AsyncGatecoClient

async def main():
    async with AsyncGatecoClient(
        "https://api.gateco.ai",
        api_key="gck_live_abc123...",
    ) as client:

        # Policy-gated retrieval — the core Gateco primitive
        result = await client.retrievals.execute(
            query="What is the CEO's salary?",
            principal_id="user_james_wu",
            connector_id="connector_hr_docs",
            search_mode="hybrid",
            alpha=0.7,   # 70% vector weight, 30% keyword
            top_k=5,
        )

        # Allowed chunks are safe to pass to your LLM
        for chunk in result.allowed_chunks:
            print(f"[ALLOWED] {chunk.resource_id} score={chunk.score}")

        # Denied chunks are redacted — only metadata is surfaced
        print(f"Denied: {result.denied_count} chunk(s)")

asyncio.run(main())

同期（スクリプトおよびノートブック）

from gateco_sdk import GatecoClient

with GatecoClient("https://api.gateco.ai", api_key="gck_live_abc123...") as client:
    result = client.retrievals.execute(
        query="What is the CEO's salary?",
        principal_id="user_james_wu",
        connector_id="connector_hr_docs",
        search_mode="hybrid",
    )
    print(result.decision)  # "DENIED"

---

利用可能な名前空間

すべての名前空間と、それぞれのすべてのメソッドは、AsyncGatecoClient（非同期）と GatecoClient（同期）の両方で利用できます。tests/test_sync_parity.py では、両者に差異があるとビルドが失敗します。

名前空間	説明
client.answers	ポリシーでフィルタリングされた引用を含む、根拠に基づく回答の合成（Team+）
client.api_keys	API キーの作成、一覧表示、削除、ローテーション
client.audit	監査ログの一覧表示と CSV エクスポート
client.auth	ログイン、サインアップ、トークンの更新、ログアウト
client.billing	プラン、使用量メーター、請求書、サブスクリプション、Stripe のチェックアウトとポータル
client.connectors	コネクターの CRUD、接続テスト、検索／取り込み設定、カバレッジ、分類候補
client.dashboard	オプションのスパークラインを含む、集計済みダッシュボード統計
client.data_catalog	アクセス制限付きリソースの一覧表示とメタデータの更新
client.groups	メンバー数をリアルタイムで表示する、読み取り専用のグループディレクトリ
client.identity_providers	ID プロバイダーの CRUD と同期（Okta、Azure Entra ID、AWS IAM、GCP）
client.ingest	単一ドキュメント、一括、ファイルの取り込み（Tier 1 コネクター）
client.onboarding	オンボーディングのステータス（算出される 6 つのステップ）とチェックリストの非表示化
client.pipelines	パイプラインの CRUD と実行管理
client.policies	ポリシーの CRUD、ライフサイクル管理（有効化／アーカイブ）、テンプレート
client.principals	プリンシパルの一覧表示、詳細表示、メールアドレスまたはプロバイダーのサブジェクトによる解決
client.relationships	REBAC の直接リレーションの CRUD — 1 ホップのタプルの作成、一覧表示、削除（Team+）
client.retroactive	既存のコネクターに対する遡及的なベクトル登録
client.retrievals	権限で制限された検索の実行、ポリシーフィルター、履歴
client.simulator	ドライラン、ライブプレビュー、一括プレビューによるアクセスシミュレーション（Growth+）
client.sources	コンテンツソースへの接続（Drive、SharePoint、Confluence、Notion）：作成、テスト、ACL カバレッジ
client.users	現在のユーザープロファイル — get_me()、update_me(name)

---

検索モード

# Vector search (default) — semantic similarity
result = await client.retrievals.execute(
    query="quarterly earnings", principal_id="...", connector_id="...",
)

# Keyword search — ranked full-text search (BM25)
result = await client.retrievals.execute(
    query="quarterly earnings", principal_id="...", connector_id="...",
    search_mode="keyword",
)

# Hybrid search — vector + keyword fused (RRF)
result = await client.retrievals.execute(
    query="quarterly earnings", principal_id="...", connector_id="...",
    search_mode="hybrid",
    alpha=0.5,   # 1.0 = all-vector, 0.0 = all-keyword
)

# Grep — exact pattern matching
result = await client.retrievals.execute(
    query="ERR-4021", principal_id="...", connector_id="...",
    search_mode="grep",
    pattern_type="regex",
    case_sensitive=False,
)

---

API キーの管理

# Create a key — the plaintext is returned exactly once
key_info = await client.api_keys.create(name="prod-worker")
print(key_info["key"])    # gck_live_abc123...  (store this securely)
print(key_info["prefix"]) # gck_live_abc

# List keys (plaintext never returned after creation)
keys = await client.api_keys.list()

# Rotate a key — old key is invalidated immediately
new_key = await client.api_keys.rotate(key_id="key-uuid-here")

# Delete a key
await client.api_keys.delete(key_id="key-uuid-here")

---

リレーションシップベースのアクセス制御（REBAC）

# Create a direct relation: Alice owns resource R
rel = await client.relationships.create(
    subject_principal_id="principal-uuid",
    relation_name="owner_of",
    object_resource_id="resource-uuid",
)
print(rel["id"])

# List relations for a principal
rels = await client.relationships.list(
    subject_id="principal-uuid",
    relation="owner_of",
)

# Delete a relation (invalidates policy cache immediately)
await client.relationships.delete(relationship_id=rel["id"])

タプルの存在に基づいてアクセスを制御するには、ポリシーの条件フィールドに relation.<name> を使用します。

# Policy rule: allow access when principal has owner_of relation on the resource
rule = {"field": "relation.owner_of", "operator": "eq", "value": True}

---

オンボーディングのステータス

# Check which onboarding steps are complete
status = await client.onboarding.status()
for step in status["steps"]:
    print(f"{step['name']:30s}  {step['status']}")

# Dismiss the checklist once the org is fully configured
await client.onboarding.dismiss()

---

プリンシパルの解決

# Resolve a principal by email (read-only — never creates)
principal = await client.principals.resolve(email="[email protected]")

# Resolve by raw IDP-side user ID
principal = await client.principals.resolve(provider_subject="okta-user-123")

# Scoped to a specific identity provider
principal = await client.principals.resolve(
    email="[email protected]",
    identity_provider_id="idp-uuid-here",
)

---

根拠に基づく回答の合成（Team+）

answer = await client.answers.execute(
    query="Summarise the Q4 revenue results.",
    principal_id="user_alice",
    connector_id="connector_finance_docs",
    search_mode="hybrid",
)

print(answer.answer_text)      # LLM-generated answer from allowed chunks only
print(answer.outcome)          # "answered" | "no_access" | "insufficient_context"
for citation in answer.citations:
    print(f"  [{citation.score:.2f}] {citation.resource_id}")

---

ポリシーの作成

# Create an RBAC policy
policy = await client.policies.create(
    name="Engineering read-only",
    description="Allow engineering group to read internal resources",
    type="rbac",
    effect="allow",
    rules=[{
        "description": "Engineering group members",
        "effect": "allow",
        "conditions": [{"field": "principal.groups", "operator": "contains", "value": "engineering"}],
        "priority": 1,
    }],
    resource_selectors=[{"field": "resource.classification", "op": "lte", "value": "internal"}],
)

ポリシーの検証ルール：

• 条件フィールドには resource.、principal.、または relation. のプレフィックスを指定する必要があります。 プレフィックスのないフィールド名（例："classification"）は 422 で拒否されます。リソースではなくプリンシパルに対して暗黙的に解決されるためです。
• resource_selectors が空のポリシーで、すべてのリソースへの適用を明示的に有効にするには、リクエスト本文に apply_to_all_resources=True を指定する必要があります。

---

検索の診断

result = await client.retrievals.execute(
    query="quarterly earnings",
    principal_id="user_alice",
    connector_id="connector_finance_docs",
    search_mode="hybrid",
)

# All retrieval responses include diagnostics
print(result.diagnostics.outcome_detail)    # Human-readable explanation
print(result.diagnostics.candidates_fetched)  # How many candidates were checked
print(result.diagnostics.candidates_denied)   # How many were denied by policy
print(result.diagnostics.refill_rounds)       # How many refill rounds ran (0 = first pass sufficient)

---

コネクターの事前チェック

# Check if a connector is production-ready before using it in retrievals
preflight = client.connectors.preflight(connector_id="...")
print(preflight.ready_for_production)  # bool
print(preflight.recommendation)        # What to fix next
for check in preflight.checks:
    print(f"{check.name}: {'PASS' if check.passed else 'FAIL'} (blocking={check.blocking})")

---

ダッシュボードのアクティベーション指標

# Aggregated dashboard statistics
stats = await client.dashboard.stats()
print(stats["total_retrievals"])
print(stats["allowed_retrievals"])

# Activation funnel metrics
activation = client.dashboard.get_activation_stats()
print(activation.total_retrievals_30d)
print(activation.allowed_retrievals_30d)
print(activation.no_access_retrievals_30d)  # Retrievals where 0 results were authorized
print(activation.p95_latency_ms)            # End-to-end p95 latency

---

ページネーション

一覧表示エンドポイントは Page オブジェクトを返します。自動で非同期ページネーションを行うには、list_all() を使用します。

async for connector in client.connectors.list_all():
    print(connector.name)

---

レート制限

3 つのエンドポイントでは、組織ごとに 1 分あたりの制限が適用されます。

エンドポイント	制限
POST /api/retrievals/execute	60/分
POST /api/answers/execute	20/分
POST /api/simulator/preview	10/分

制限を超えると RateLimitError が発生します。SDK は指数バックオフを使用して自動的に再試行します（max_retries で設定可能）。制限は組織単位で適用され、プロセスの再起動時にリセットされます（メモリ内での実装）。

---

エラー処理

from gateco_sdk.errors import NotFoundError, RateLimitError, AuthenticationError

try:
    conn = await client.connectors.get("nonexistent-id")
except NotFoundError:
    print("Connector not found")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid or expired credentials")

---

CLI

gateco コマンドは SDK とともにインストールされ、同じ認証情報を使用します。

# Log in once; you are prompted for the password (or pipe it on stdin).
# Passing --password on the command line works but lands in shell history.
gateco login --email [email protected]

gateco whoami                       # base URL, credential in use, key scopes

# Connectors: inspect and configure (user session only)
gateco connectors list
gateco connectors get <connector_id>
gateco connectors get-search-config <connector_id>
gateco connectors set-search-config <connector_id> --json '{"table_name": "docs", "vector_column": "embedding", "content_column": "text"}'
gateco connectors get-ingestion-config <connector_id>
gateco connectors set-ingestion-config <connector_id> --file ingestion.json

# Ingest: .txt/.md are sent as text; PDF, Word, PowerPoint, Excel and CSV are uploaded
gateco ingest report.txt --connector-id <id> --classification confidential --sensitivity high
gateco ingest "Q3 board deck.pdf" --connector-id <id> --classification confidential --sensitivity high --domain finance
gateco ingest-batch ./documents --connector-id <id> --glob "*.md"

# Retrieve as a principal (API key with the retrieve scope, or a session)
gateco retrieve --connector-id <id> --principal-id <id> --query "revenue report" --search-mode hybrid

--classification は public、internal、confidential、restricted を受け付けます。 --sensitivity は low、medium、high、critical を受け付けます（一覧は gateco ingest --help を参照）。

---

MCP サーバー（Model Context Protocol）

オプションの MCP サーバーを使うと、AI エージェント（Claude Desktop、Cursor など）がカスタムコードなしで、権限を考慮した検索を実行できます。

pip install gateco[mcp]

# Start the server
gateco mcp serve

# Or use the direct entry point (for MCP host configs)
gateco-mcp

Claude Desktop の設定

{
  "mcpServers": {
    "gateco": {
      "command": "gateco-mcp",
      "env": {
        "GATECO_API_KEY": "gck_live_abc123...",
        "GATECO_BASE_URL": "https://api.gateco.ai"
      }
    }
  }
}

利用可能な MCP ツール

ツール	説明
gateco_retrieve	権限を考慮した検索（ベクトル／キーワード／ハイブリッド／grep）
gateco_ask	検索モードを使用した、根拠に基づく回答の生成（Team+）
gateco_check_access	アクセスのドライランシミュレーション（Growth+）。ユーザーセッションのみ（gateco login）。API キーでは呼び出せません
gateco_list_connectors	準備状況レベルとともにコネクターを一覧表示
gateco_list_principals	ID プリンシパルを一覧表示
gateco_list_groups	ライブのメンバー数とともに、グループ（IdP 同期済みおよびローカルディレクトリ）を一覧表示。2026-10-02 以降のバックエンドに対しては、retrieve スコープのキーで使用できます。それ以前のバックエンドでは、ユーザーセッションが必要であることを示す応答が返されます
gateco_resolve_principal	メールアドレスまたはプロバイダーのサブジェクトからプリンシパルを解決

すべてのツールは Markdown 形式のテキストを返します。拒否されたコンテンツが公開されることはありません。拒否理由と件数のみが表示されます。

---

開発

pip install -e ".[dev]"
pytest -v

# Run MCP server tests
pytest tests/test_mcp/ -v

# With coverage
pytest --cov=src/gateco_sdk

---

リンク

• ドキュメント
• ダッシュボード
• GitHub
• バグトラッカー
• サポート