Skill: maxiiwang/cogmate-client (version 1.0.1)

--- name: cogmate-client description: Access Cogmate personal knowledge systems via API. Use when querying someone's Cogmate/模拟世界 for knowledge retrieval, semantic search, or Q&A. Requires valid access token from CogNexus (https://github.com/MaxiiWang/CogNexus). Triggers on: "ask Cogmate", "query knowledge base", "search Cogmate", "access 模拟世界". --- # Cogmate Client Connect to Cogmate instances for knowledge retrieval and Q&A. ## Prerequisites - Valid access token (obtain from [CogNexus](https://cognexus.example.com) or instance owner) - Cogmate API endpoint URL ## Quick Start ### Ask a Question ```bash curl -X POST "http://{COGMATE_URL}/api/ask?[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"question": "你的问题"}' ``` ### Semantic Search ```bash curl "http://{COGMATE_URL}/api/visual/facts?[REDACTED_SECRET]" ``` ## API Reference ### Authentication All protected endpoints require `token` as **query parameter** (not JSON body). ### Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/api/ask` | POST | Ask questions, get AI-powered answers | | `/api/visual/facts` | GET | Browse/search knowledge facts | | `/api/visual/stats` | GET | Get knowledge base statistics | | `/api/visual/graph` | GET | Get knowledge graph data | | `/api/hub/profile` | GET | Get Cogmate profile (public) | ### POST /api/ask?[REDACTED_SECRET] Ask a question against the knowledge base. **Request:** ```json { "question": "What do you know about X?" } ``` **Response:** ```json { "answer": "Based on the knowledge base...", "sources": [{"id": "fact_xxx", "summary": "..."}] } ``` ### GET /api/visual/facts Browse or search facts. **Parameters:** - `token` (required): Access token - `search` (optional): Search query - `layer` (optional): Filter by layer (fact/connection/abstract) ### GET /api/visual/stats Get statistics about the knowledge base. **Response:** ```json { "facts": 87, "connections": 45, "abstracts": 12 } ``` ## Token Permissions | Scope | Capabilities | |-------|-------------| | `full` | Complete access: browse, ask, view private | | `qa_public` | Q&A only (may have usage limits) | | `browse_public` | Browse public facts only | ## Helper Scripts ### Ask Question ```bash ./scripts/ask.sh <cogmate_url> <token> "Your question" ``` ### Search Knowledge ```bash ./scripts/search.sh <cogmate_url> <token> "search term" ``` ## Getting Access 1. Visit the Cogmate owner's CogNexus marketplace listing 2. Purchase a token with ATP (platform credits) 3. Use the token to access the Cogmate API ## Error Handling | Status | Meaning | |--------|---------| | 401 | Invalid or expired token | | 403 | Insufficient permissions | | 429 | Rate limit exceeded | | 500 | Server error | ## Example Workflow ```python import requests COGMATE_URL = "http://example.com:8000" [REDACTED_SECRET]" # Ask a question (token in query params, question in body) response = requests.post( f"{COGMATE_URL}/api/ask", params={"token": TOKEN}, json={"question": "What are the key insights about X?"} ) print(response.json()["answer"]) # Search facts facts = requests.get( f"{COGMATE_URL}/api/visual/facts", params={"token": TOKEN, "search": "keyword"} ).json() for fact in facts.get("facts", []): print(f"- {fact['summary']}") ```

path: references/api-details.md
content: # Cogmate API Details

## Full Endpoint Reference

### Public Endpoints (No Token Required)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/hub/profile` | GET | Get Cogmate profile info |
| `/api/public/info` | GET | Basic instance info |
| `/health` | GET | Health check |

### Protected Endpoints (Token Required)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/ask` | POST | Ask questions |
| `/api/visual/facts` | GET | List/search facts |
| `/api/visual/stats` | GET | Knowledge statistics |
| `/api/visual/graph` | GET | Graph visualization data |
| `/api/visual/health` | GET | Detailed health metrics |
| `/api/auth/check` | GET | Verify token validity |

## Request/Response Examples

### /api/hub/profile

**Response:**
```json
{
  "name": "Agent Name",
  "title": "Knowledge Explorer",
  "bio": "A personal knowledge management system...",
  "avatar": "",
  "stats": {"facts": 87},
  "api_version": "1.0"
}
```

### /api/ask?[REDACTED_SECRET]

**Request:**
```json
{
  "question": "What are the key concepts?"
}
```

> **Note:** Token must be passed as query parameter, not in JSON body.

**Response:**
```json
{
  "answer": "Based on the knowledge base, the key concepts are...",
  "sources": [
    {"id": "fact_001", "summary": "Source fact 1"},
    {"id": "fact_002", "summary": "Source fact 2"}
  ],
  "confidence": 0.85
}
```

### /api/visual/facts

**Query Parameters:**
- `token`: Access token (required)
- `search`: Search query (optional)
- `layer`: Filter by layer - fact/connection/abstract (optional)
- `limit`: Max results (optional, default 50)
- `offset`: Pagination offset (optional)

**Response:**
```json
{
  "facts": [
    {
      "id": "fact_001",
      "summary": "Key insight about topic X",
      "layer": "fact",
      "created_at": "2026-03-10T12:00:00Z",
      "tags": ["topic", "insight"]
    }
  ],
  "total": 87,
  "has_more": true
}
```

### /api/visual/stats

**Response:**
```json
{
  "facts": 87,
  "connections": 45,
  "abstracts": 12,
  "total_nodes": 144,
  "total_edges": 89
}
```

### /api/auth/check

**Query:** `?[REDACTED_SECRET]`

**Response:**
```json
{
  "valid": true,
  "scope": "qa_public",
  "permissions": {
    "chat": true,
    "browse": false,
    "full_access": false
  },
  "usage": {
    "qa_limit": 10,
    "qa_used": 3,
    "qa_remaining": 7
  },
  "expires_at": "2026-03-28T00:00:00Z"
}
```

## Error Responses

All errors return JSON:

```json
{
  "detail": "Error message",
  "error_code": "INVALID_TOKEN"
}
```

### Common Error Codes

| Code | Status | Description |
|------|--------|-------------|
| INVALID_TOKEN | 401 | Token not found or expired |
| INSUFFICIENT_SCOPE | 403 | Token lacks required permission |
| QUOTA_EXCEEDED | 429 | Usage limit reached |
| NOT_FOUND | 404 | Resource not found |
| INTERNAL_ERROR | 500 | Server error |

## Rate Limits

- `qa_public` tokens: Limited by `qa_limit` in token metadata
- `full` tokens: No hard limit, but reasonable use expected
- All tokens: 60 requests/minute per token


path: scripts/ask.sh
content: #!/bin/bash
# Ask a question to Cogmate
# Usage: ./ask.sh <cogmate_url> <token> "question"

COGMATE_URL="${1%/}"
TOKEN="$2"
QUESTION="$3"

if [ -z "$COGMATE_URL" ] || [ -z "$TOKEN" ] || [ -z "$QUESTION" ]; then
    echo "Usage: $0 <cogmate_url> <token> \"question\""
    echo "Example: $0 http://example.com:8000 tok_xxx \"What do you know about AI?\""
    exit 1
fi

curl -s -X POST "${COGMATE_URL}/api/ask?[REDACTED_SECRET]" \
    -H "Content-Type: application/json" \
    -d "{\"question\": \"${QUESTION}\"}" | \
    python3 -c "import sys,json; r=json.load(sys.stdin); print(r.get('answer','No answer'))"


path: scripts/search.sh
content: #!/bin/bash
# Search facts in Cogmate
# Usage: ./search.sh <cogmate_url> <token> "search term"

COGMATE_URL="${1%/}"
TOKEN="$2"
SEARCH="$3"

if [ -z "$COGMATE_URL" ] || [ -z "$TOKEN" ]; then
    echo "Usage: $0 <cogmate_url> <token> [search_term]"
    echo "Example: $0 http://example.com:8000 tok_xxx \"AI\""
    exit 1
fi

PARAMS="[REDACTED_SECRET]"
[ -n "$SEARCH" ] && PARAMS="${PARAMS}&search=${SEARCH}"

curl -s "${COGMATE_URL}/api/visual/facts?${PARAMS}" | \
    python3 -c "
import sys, json
data = json.load(sys.stdin)
facts = data.get('facts', [])
if not facts:
    print('No facts found.')
else:
    for f in facts[:10]:
        print(f\"- [{f.get('layer','?')}] {f.get('summary','')}\")
"


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)