asta-documents

Asta Documents Management

このスキルは、asta documents CLI を使用して、研究論文、ドキュメント、リソースを追跡するための包括的なドキュメント管理機能を提供します。

機能： ドキュメントのメタデータ（URL、要約、タグ）をローカルインデックスで追跡します。強力な検索機能を備えたスマートなブックマークマネージャーのようなものです。

デフォルトのインデックスの場所： .asta/documents/index.yaml（現在の作業ディレクトリからの相対パス）。デフォルトの場所を使用する場合、--index-path フラグは省略できます。カスタムのインデックスの場所やリモートインデックスを使用する場合にのみ必要です。

.asta ドキュメントの自動インデックス作成

重要： 他の Asta スキル（文献調査など）が .asta/（現在の作業ディレクトリ内）にドキュメントを書き込む場合は、ドキュメントストアに自動的にインデックスを作成してください。これにより、Asta が生成したすべてのドキュメントが追跡され、検索可能になります。

ワークフロー：

1. Asta スキルが .asta/ にファイルを書き込んだ後（例：文献レポート、論文コレクション）
2. 新しいドキュメントがないかディレクトリをスキャンします
3. 各ドキュメントについて、適切なメタデータを付けてインデックスに追加します：
   • name：ファイル名またはドキュメントのタイトルから取得します
   • url：ローカルパスを指す file:// URL を使用します（file:// URL には絶対パスを使用してください）
   • summary：ドキュメントの内容から抽出するか、簡潔な説明を使用します
   • tags：関連するタグを追加します（例：「asta-generated」、「literature-report」など）
   • mime-type：ファイル拡張子から判定します（例：「text/markdown」、「application/pdf」）

例：

# After a literature report is written to .asta/literature/report/2024-01-15-ml.md
# Convert relative path to absolute for file:// URL
REPORT_PATH="$(pwd)/.asta/literature/report/2024-01-15-ml.md"
asta documents add "file://${REPORT_PATH}" \
  --name="Literature Report: Machine Learning" \
  --summary="Comprehensive report on machine learning papers from 2023-2024" \
  --tags="asta-generated,literature-report,ml" \
  --mime-type="text/markdown"

コマンドのクイックリファレンス

機械可読な出力を得るには、任意のコマンドに --json フラグを追加します。 デフォルトでは .asta/documents/index.yaml を使用します（カスタムの場所には --index-path <file> を追加します）。

# List documents
asta documents list
asta documents list --tags="ai,research"

# Search documents (by field)
asta documents search --summary="query"
asta documents search --name="title words"
asta documents search --tags="ai,nlp"
asta documents search --extra=".year > 2020"

# Multi-field search (intersection - matches ALL)
asta documents search --summary="transformers" --tags="ai"

# Multi-field search (union - matches ANY)
asta documents search --summary="transformers" --name="BERT" --union

# Add document (use absolute path for file:// URLs)
asta documents add <url> \
  --name="Title" \
  --summary="Description" \
  --tags="tag1,tag2" \
  --extra='{"author": "Smith et al", "year": 2024, "venue": "NeurIPS"}'

# Get document metadata
asta documents get <uuid>

# Update document
asta documents update <uuid> \
  --name="New Title" \
  --tags="new,tags"

# Fetch document content
asta documents fetch <uuid> -o /tmp/document.pdf

# Manage tags
asta documents add-tags <uuid> --tags="new,tags"
asta documents remove-tags <uuid> --tags="old,tags"

# Cache management
asta documents cache list
asta documents cache stats
asta documents cache clean --days 7

# Summary information (document counts)
asta documents show

インデックス管理とキャッシュを適切に行うため、すべての操作には必ずコマンドラインインターフェースを使用してください。 インデックスファイルを直接読み書きする操作は避けてください。

リモートインデックスの操作（asta:// URL）

Asta ドキュメントでは、asta:// URL スキームを使用してリモートインデックスを参照できます。これにより、ウェブ上でホストされているドキュメントコレクションを共有できます。

URL 形式：

asta://{url-encoded-index-url}/{uuid}

説明：

• {url-encoded-index-url} は、リモートの index.yaml ファイルへの URL を URL エンコードしたものです
• {uuid} は10文字のドキュメント識別子です

例：

# Actual index URL: https://example.com/research/index.yaml
# Asta URL: asta://https%3A%2F%2Fexample.com%2Fresearch%2Findex.yaml/6MNxGbWGRC

ワークフロー：

asta:// URL に遭遇した場合は、次の手順に従ってください：

1. URL を解析し、エンコードされたインデックス URL とドキュメント UUID を抽出します
2. インデックス URL を URL デコードします
3. リモートインデックスをダウンロードし、ローカルの一時ファイルに保存します
4. --index-path パラメーターを使用して ドキュメントにアクセスします

例：

# Given an asta:// URL
ASTA_URL="asta://https%3A%2F%2Fexample.com%2Fresearch%2Findex.yaml/6MNxGbWGRC"

# 1. Parse the URL components (extract encoded index URL and UUID)
ENCODED_INDEX_URL=$(echo "$ASTA_URL" | sed 's|^asta://||' | sed 's|/[^/]*$||')
UUID=$(echo "$ASTA_URL" | sed 's|.*/||')

# 2. URL-decode the index URL
INDEX_URL=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$ENCODED_INDEX_URL'))")

# 3. Download the remote index
curl -s -o /tmp/remote-index.yaml "$INDEX_URL"

# 4. Get document metadata using --index-path
asta documents get "$UUID" --index-path /tmp/remote-index.yaml

# 5. Fetch document content
asta documents fetch "$UUID" --index-path /tmp/remote-index.yaml -o /tmp/document.pdf

リモートインデックスでの一般的な操作：

# After downloading and decoding the index URL (see examples above)
# Assume TEMP_INDEX points to the downloaded index file

# Search remote index
asta documents search --summary="query" --index-path "$TEMP_INDEX"

# List all documents in remote index
asta documents list --index-path "$TEMP_INDEX"

# Get metadata for specific document
asta documents get "$UUID" --index-path "$TEMP_INDEX"

# Search and fetch from remote index
asta documents search --summary="transformers" --index-path "$TEMP_INDEX" --show-scores
asta documents fetch "$UUID" --index-path "$TEMP_INDEX" -o result.pdf

重要な注意事項：

• --index-path パラメーターは、すべての読み取りコマンド（list、search、get、fetch）で使用できます
• この方法でアクセスするリモートインデックスは読み取り専用です（add/update/remove 操作はできません）
• ダウンロードしたインデックスは、ダウンロードの繰り返しを避けるため、ローカルにキャッシュできます
• インデックス URL の部分は URL エンコードされているため、使用前にデコードする必要があります
• デコード後の URL では、http://、https://、file://、s3://、gs:// を使用できます
• 使用する前に、インデックスファイルが存在し、有効な YAML であることを必ず確認してください

完全なワークフローの例：

# User provides: asta://https%3A%2F%2Fai.example.org%2Fpapers%2Findex.yaml/AbC123XyZ9

# Step 1: Extract components
ASTA_URL="asta://https%3A%2F%2Fai.example.org%2Fpapers%2Findex.yaml/AbC123XyZ9"
ENCODED_INDEX_URL=$(echo "$ASTA_URL" | sed 's|^asta://||' | sed 's|/[^/]*$||')
UUID=$(echo "$ASTA_URL" | sed 's|.*/||')

# Step 2: URL-decode the index URL
INDEX_URL=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$ENCODED_INDEX_URL'))")
# Result: https://ai.example.org/papers/index.yaml

# Step 3: Download index to temp location
TEMP_INDEX="/tmp/asta-index-$(date +%s).yaml"
curl -s -o "$TEMP_INDEX" "$INDEX_URL"

# Step 4: Verify download succeeded
if [ ! -f "$TEMP_INDEX" ]; then
    echo "Failed to download index from $INDEX_URL"
    exit 1
fi

# Step 5: Access the document
asta documents get "$UUID" --index-path "$TEMP_INDEX"
asta documents fetch "$UUID" --index-path "$TEMP_INDEX" -o /tmp/paper.pdf

# Step 6: Read the content
# Read(/tmp/paper.pdf)

ドキュメントの内容を取得する

インデックスにはメタデータのみが保存されます。ドキュメントの内容は、その URL から取得できます。fetch コマンドは内容を取得し、次回以降の利用に備えてローカルにキャッシュします。

ファイルに取得（自動キャッシュあり）：

asta documents fetch <uuid> -o /tmp/document.pdf

対応する URL プロトコル

このシステムは、ドキュメント URL に複数のプロトコルをサポートしています：

ローカルおよびウェブ：

• http:// と https:// - ウェブ URL（curl を使用）
• file:// - ローカルファイルシステム（curl を使用）

クラウドストレージ：

• s3:// - Amazon S3（AWS CLI が必要）
• gs:// - Google Cloud Storage（gsutil が必要）

クラウドストレージのセットアップ：

S3 の場合：

# Install AWS CLI
brew install awscli  # macOS
pip install awscli   # or via pip

# Configure credentials
aws configure
# Or use: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE

GCS の場合：

# Install Google Cloud SDK
brew install --cask google-cloud-sdk  # macOS

# Authenticate
gcloud auth login
# Or use: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

例：

# Add document from S3
asta documents add s3://my-bucket/papers/research.pdf \
  --name="Research Paper" \
  --summary="ML research findings" \
  --tags="ml,research"

# Add document from GCS
asta documents add gs://my-bucket/docs/spec.pdf \
  --name="Technical Spec" \
  --summary="System specifications" \
  --tags="docs"

# Fetch works the same for all protocols
asta documents fetch <uuid> -o local-copy.pdf

キャッシュ管理

キャッシュされた項目を一覧表示：

asta documents cache list

キャッシュの統計情報を表示：

asta documents cache stats

古いキャッシュエントリを削除：

# Remove items older than N days
asta documents cache clean --days 14

キャッシュ全体をクリア：

asta documents cache clear
asta documents cache clear -y  # Skip confirmation

特定の項目の詳細を表示：

asta documents cache info <hash>

一般的なワークフロー

ワークフロー 1：Asta で生成されたドキュメントをインデックス化する

# After literature find writes to .asta/
# List all files in .asta/
ls -la .asta/

# For each new document, add to index (convert to absolute path for file:// URL)
REPORT_PATH="$(pwd)/.asta/literature/report/literature-report.md"
asta documents add "file://${REPORT_PATH}" \
  --name="Literature Report: Transformers" \
  --summary="Research findings on transformer architectures" \
  --tags="asta-generated,literature-report,transformers" \
  --mime-type="text/markdown"

# Now the document is searchable
asta documents search --tags="asta-generated"

ワークフロー 2：論文を追加して整理する

# Add research paper
asta documents add https://arxiv.org/pdf/1706.03762.pdf \
  --name="Attention Is All You Need" \
  --summary="Seminal paper introducing Transformer architecture" \
  --tags="ai,research,nlp,transformers" \
  --mime-type="application/pdf" \
  --extra='{"author": "Vaswani et al", "year": 2017, "venue": "NeurIPS"}'

# Search papers by tag
asta documents search --tags="transformers"

ワークフロー 3：検索して取得する

# Search for relevant documents
asta documents search --summary="transformer architecture" --show-scores

# Get metadata for top result (using UUID from search results)
asta documents get 6MNxGbWGRC

# Fetch content
asta documents fetch 6MNxGbWGRC -o /tmp/paper.pdf -q

# Read with PDF support
# Read(/tmp/paper.pdf)

ワークフロー 4：JSON 処理を使って検索する

# Search and extract UUIDs
RESULTS=$(asta documents search --summary="query" --json)

# Get first UUID (example with Python)
UUID=$(echo "$RESULTS" | python3 -c "import sys,json; results=json.load(sys.stdin); print(results[0]['result']['uuid'] if results else '')")

# Fetch that document
asta documents fetch "$UUID" -o result.pdf

ワークフロー 5：タグを一括管理する

# List documents with old tag
DOCS=$(asta documents list --tags="old-tag" --json)

# For each, remove old tag and add new
for uuid in $(echo "$DOCS" | python3 -c "import sys,json; print('\\n'.join([d['uuid'] for d in json.load(sys.stdin)]))"); do
    asta documents remove-tags "$uuid" --tags="old-tag"
    asta documents add-tags "$uuid" --tags="new-tag"
done

ワークフロー 6：複数のフィールドを更新する

# Get current metadata (using UUID)
asta documents get 6MNxGbWGRC

# Update multiple fields
asta documents update 6MNxGbWGRC \
  --name="Updated Title" \
  --summary="Updated summary with more details" \
  --tags="updated,revised,2025"

ワークフロー 7：キャッシュをメンテナンスする

# Check cache usage
asta documents cache stats

# List what's cached
asta documents cache list

# Remove old entries if cache is large
asta documents cache clean --days 7

# Verify cache reduction
asta documents cache stats

フィールド別検索

Asta は、各ドキュメントフィールドに最適化された異なる検索戦略を使用します。単一のフィールドを検索することも、積集合／和集合モードで複数のフィールドを組み合わせることもできます。

単一フィールド検索

--summary（概要検索）：

• 利用可能な最適な方法を自動的に使用します：
  • ハイブリッド（BM25 + セマンティック埋め込み）→ 最も高品質
  • BM25（キーワード関連度ランキング）→ インデックス化済みで高速
  • FTS5（全文検索）→ フォールバック
  • シンプル（部分文字列照合）→ 常に利用可能
• 自然言語クエリに最適化されています
• 意味を理解します
• ランキング用の関連度スコアを生成します
• 例：asta documents search --summary="papers about transformers"

--name（名前検索）：

• 大文字と小文字を区別しない単純な単語照合
• クエリを単語に分割し、名前に含まれるいずれかの単語を照合します
• スコア =（一致した単語数 / クエリ内の総単語数）
• 高速で、インデックス作成は不要です
• ランキング用の一致スコアを生成します
• 例：asta documents search --name="Attention"

--tags（タグ検索）：

• カンマ区切りのタグ照合
• 大文字と小文字を区別しません
• フィルターとして機能します（有意な関連度スコアはありません）
• 一致するタグを1つでも持つドキュメントを検索します
• 例：asta documents search --tags="ai,nlp"

--extra（追加メタデータ検索）：

• JSONPath に似たクエリ構文
• サポートされる演算子：>, >=, <, <=, ==, contains
• 数値と文字列の比較
• フィルターとして機能します（有意な関連度スコアはありません）
• 例：
  • asta documents search --extra=".year > 2020"
  • asta documents search --extra=".author contains Smith"
  • asta documents search --extra=".venue == NeurIPS"

複数フィールド検索

複数のフィールドクエリを組み合わせて、強力なフィルター付き検索を作成できます：

積集合モード（デフォルト）：

• 指定したすべてのフィールドクエリに一致するドキュメントを返します
• 例：asta documents search --summary="transformers" --tags="ai"
• 概要に "transformers" が含まれ、かつタグに "ai" が含まれるドキュメントのみを返します

和集合モード（--union フラグ）：

• 指定したフィールドクエリのいずれかに一致するドキュメントを返します
• 例：asta documents search --summary="transformers" --name="BERT" --union
• 概要に "transformers" が含まれる、または名前に "BERT" が含まれるドキュメントを返します

階層的スコアリング：

結果は優先順位の階層に従って並べ替えられ、タグ／追加メタデータはフィルターとして機能します：

1. 概要スコア（最優先）- --summary が指定されている場合

   • セマンティック／ハイブリッド検索の関連度を使用します
   • 自然言語クエリに最適です

2. 名前スコア（中程度の優先度）- --name が指定されている場合

   • 単語照合スコアを使用します
   • 概要クエリがない場合に使用されます

3. 作成タイムスタンプ（最も低い優先度）- --tags または --extra のみが指定されている場合

   • 作成時刻の順（新しい順）に並べ替えます
   • 概要／名前クエリがない場合にのみ使用されます

例：

# Summary + tags: Sorted by summary relevance (tags filter)
asta documents search --summary="machine learning" --tags="ai"

# Name + tags: Sorted by name word-match (tags filter)
asta documents search --name="Python" --tags="programming"

# Tags only: Sorted by creation timestamp
asta documents search --tags="research"

# Three fields: Summary ranks, name and extra filter
asta documents search --summary="transformers" --name="Attention" --extra=".year > 2015"

出力形式

人間が読みやすい形式（デフォルト）：

• 書式設定されたテーブルとリスト
• 色分け表示（ターミナルが対応している場合）
• 進行状況メッセージ

JSON（--json フラグ）：

• 機械可読形式
• すべてのフィールドを含みます
• スクリプト作成や統合に使用します

詳細表示（リスト用の -v フラグ）：

• すべてのメタデータフィールドを表示します
• 追加メタデータを含みます
• URI とタイムスタンプをすべて表示します

ベストプラクティス

1. Asta のドキュメントを自動でインデックス化する：ほかのスキルが .asta/ に書き込むドキュメントは、必ずインデックス化してください（デフォルトでは .asta/documents/index.yaml を使用します）
2. 説明的な要約を使用する：要約は検索対象になります
3. タグを一貫して付ける：タグ付けのルール（例：自動インデックス化されたドキュメントには「asta-generated」）を決めてください
4. 追加のメタデータを使用する：論文には著者、年、掲載誌を保存してください
5. キャッシュ処理は fetch に任せる：キャッシュを手動で確認しないでください
6. スクリプトには JSON を使用する：テキストの解析よりも信頼性が高くなります
7. スクリプトでは静音モードを使用する：-q は進行状況のメッセージを抑制します
8. file:// URL には絶対パスを使用する：$(pwd)/ を使って相対パスを変換し、正しく解決されるようにしてください

トラブルシューティング

「asta-documents: command not found」

• 初回使用時にコマンドが自動インストールされます
• インストールを確認します：uv tool list | grep asta
• PATH に追加します：export PATH="$HOME/.local/bin:$PATH"
• 手動でインストールします：uv tool install git+https://github.com/allenai/asta-resource-repo.git

「Document not found」

• UUID を確認します：asta documents list --json | grep <partial-uuid>
• 名前空間を確認します：UUID は名前空間ごとに異なります
• .asta/documents/index.yaml にインデックスファイルがあることを確認します

「Fetch failed」

• URL にアクセスできることを確認します：curl -I <url>
• 強制的に更新してみます：--force
• ネットワーク接続を確認します

「Search returns no results」

• よりシンプルな検索語を試します
• 完全一致するものを名前またはタグで検索します：
  • asta documents search --name="keyword"
  • asta documents search --tags="tag"
• ドキュメントが存在するか確認します：asta documents list
• 複数のフィールドを使用している場合は、ユニオンモードを試します：--union

「Cache is large」

• サイズを確認します：asta documents cache stats
• 古いエントリーを削除します：asta documents cache clean --days 7
• 必要に応じて消去します：asta documents cache clear -y

更新

asta-documents CLI を更新する：

uv tool install --reinstall git+https://github.com/allenai/asta-resource-repo.git

リンク

• リポジトリ：https://github.com/allenai/asta-resource-repo
• ドキュメント：https://github.com/allenai/asta-resource-repo/blob/main/README.md
• 課題：https://github.com/allenai/asta-resource-repo/issues