insighta-sdk 0.1.0__tar.gz

insighta_sdk-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Workspaces (input/output per portfolio)
+workspaces/*
+
+credentials.yaml
+!templates/credentials.yaml
+.insighta.yaml
+
+__pycache__/
+*.pyc
+*.egg-info/
+
+.venv/
+.cache/
+.gitkeep

insighta_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to insighta-sdk
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to this project.
+
+## Development Setup
+
+### Requirements
+
+- Python 3.10+
+- pip
+
+### Installation
+
+```bash
+git clone https://github.com/insighta-cloud/insighta-sdk.git
+cd insighta-sdk
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Code Style
+
+- Follow PEP 8
+- All comments and docstrings in English
+- Type hints required for public APIs
+- Use `Decimal` for financial values, never `float`
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new API method
+fix: correct rate lookup for edge case
+docs: update README
+test: add missing test for merge_and_sort_groups
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Write tests for new functionality
+4. Ensure all tests pass (`pytest`)
+5. Submit a pull request against `main`
+
+## Multilingual Support (i18n)
+
+This project uses **English** as the primary language for:
+- Source code, comments, and docstrings
+- README and documentation
+- Commit messages and PR descriptions
+
+User-facing messages (CLI output, error messages) may support multiple locales via the i18n system in `insighta-cli`. When adding translatable strings:
+- Add the English key first
+- Use ICU MessageFormat or simple key-value pairs
+- Keep keys descriptive (e.g., `upload_success`, not `msg_01`)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the CC-BY-NC-4.0 license.

insighta_sdk-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2026 Insighta Cloud Inc.
+
+You are free to:
+
+  Share — copy and redistribute the material in any medium or format
+  Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made.
+
+  NonCommercial — You may not use the material for commercial purposes.
+
+  No additional restrictions — You may not apply legal terms or technological
+  measures that legally restrict others from doing anything the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-nc/4.0/legalcode

insighta_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: insighta-sdk
+Version: 0.1.0
+Summary: Insighta Cloud SDK - API client and data models
+Project-URL: Homepage, https://insighta.cloud
+Author: insighta cloud Inc.
+License-Expression: CC-BY-NC-4.0
+License-File: LICENSE
+Keywords: api-client,insighta,investment,portfolio,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# insighta-sdk
+
+Insighta Cloud SDK — API client and data models for portfolio management.
+
+## Installation
+
+```bash
+pip install insighta-sdk
+```
+
+## Quick Start
+
+```python
+from insighta_sdk import Credentials, InsightaClient
+
+creds = Credentials.from_file("credentials.yaml")
+client = InsightaClient(creds)
+
+# List portfolios
+portfolios = client.get_portfolios()
+
+# Create a portfolio
+from insighta_sdk import UploadConfig
+config = UploadConfig.from_file("upload.yaml")
+portfolio_id = client.create_portfolio(config)
+```
+
+## Features
+
+- **API Client** — Full coverage of Insighta OpenAPI (portfolios, orders, metrics)
+- **Data Models** — `Trade`, `Holding`, `Deposit`, `OrderGroup`, `CashDeposit`, `RateEntry`
+- **Utilities** — Rate lookup, order grouping, deposit merging
+- **Workspace Management** — `Dirs` class for consistent file path resolution
+
+## API Reference
+
+### Client
+
+| Method | Description |
+|--------|-------------|
+| `create_portfolio(config)` | Create a new portfolio |
+| `get_portfolios()` | List own portfolios |
+| `search_portfolios(...)` | Search public portfolios |
+| `delete_portfolio(id)` | Delete a portfolio |
+| `send_order(portfolio_id, group, currency)` | Submit an order group |
+| `get_nav_history(id)` | Get NAV history |
+| `get_metrics_history(id, ...)` | Get metrics (TWR, etc.) |
+
+### Utilities
+
+| Function | Description |
+|----------|-------------|
+| `load_order_groups(path)` | Parse order.csv into OrderGroup list |
+| `load_cash_deposits(path)` | Parse cash_deposits.csv |
+| `merge_and_sort_groups(orders, deposits, memos)` | Merge and sequence order groups |
+| `load_rate_file(path)` | Load exchange rate CSV |
+| `lookup_rate(entries, dt, cur, base)` | Find applicable rate for a trade |
+| `fetch_ticker_info(tickers)` | Query ticker metadata from API |
+
+## API Endpoints
+
+| Environment | Base URL |
+|-------------|----------|
+| Production | `https://openapi.insighta.cloud` |
+| Development | `https://dev.openapi.insighta.cloud` |
+
+OpenAPI spec: [`insighta-app/openapi-docs/`](https://github.com/insighta-cloud/insighta/tree/main/insighta-app/openapi-docs)
+
+## Development
+
+```bash
+pip install -e .
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+CC-BY-NC-4.0 — See [LICENSE](LICENSE)

insighta_sdk-0.1.0/README.md

@@ -0,0 +1,80 @@
+# insighta-sdk
+
+Insighta Cloud SDK — API client and data models for portfolio management.
+
+## Installation
+
+```bash
+pip install insighta-sdk
+```
+
+## Quick Start
+
+```python
+from insighta_sdk import Credentials, InsightaClient
+
+creds = Credentials.from_file("credentials.yaml")
+client = InsightaClient(creds)
+
+# List portfolios
+portfolios = client.get_portfolios()
+
+# Create a portfolio
+from insighta_sdk import UploadConfig
+config = UploadConfig.from_file("upload.yaml")
+portfolio_id = client.create_portfolio(config)
+```
+
+## Features
+
+- **API Client** — Full coverage of Insighta OpenAPI (portfolios, orders, metrics)
+- **Data Models** — `Trade`, `Holding`, `Deposit`, `OrderGroup`, `CashDeposit`, `RateEntry`
+- **Utilities** — Rate lookup, order grouping, deposit merging
+- **Workspace Management** — `Dirs` class for consistent file path resolution
+
+## API Reference
+
+### Client
+
+| Method | Description |
+|--------|-------------|
+| `create_portfolio(config)` | Create a new portfolio |
+| `get_portfolios()` | List own portfolios |
+| `search_portfolios(...)` | Search public portfolios |
+| `delete_portfolio(id)` | Delete a portfolio |
+| `send_order(portfolio_id, group, currency)` | Submit an order group |
+| `get_nav_history(id)` | Get NAV history |
+| `get_metrics_history(id, ...)` | Get metrics (TWR, etc.) |
+
+### Utilities
+
+| Function | Description |
+|----------|-------------|
+| `load_order_groups(path)` | Parse order.csv into OrderGroup list |
+| `load_cash_deposits(path)` | Parse cash_deposits.csv |
+| `merge_and_sort_groups(orders, deposits, memos)` | Merge and sequence order groups |
+| `load_rate_file(path)` | Load exchange rate CSV |
+| `lookup_rate(entries, dt, cur, base)` | Find applicable rate for a trade |
+| `fetch_ticker_info(tickers)` | Query ticker metadata from API |
+
+## API Endpoints
+
+| Environment | Base URL |
+|-------------|----------|
+| Production | `https://openapi.insighta.cloud` |
+| Development | `https://dev.openapi.insighta.cloud` |
+
+OpenAPI spec: [`insighta-app/openapi-docs/`](https://github.com/insighta-cloud/insighta/tree/main/insighta-app/openapi-docs)
+
+## Development
+
+```bash
+pip install -e .
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+CC-BY-NC-4.0 — See [LICENSE](LICENSE)

insighta_sdk-0.1.0/insighta_sdk/__init__.py

@@ -0,0 +1,41 @@
+"""Insighta Cloud SDK - API client and data models."""
+
+from .client import InsightaClient
+from .models import (
+    Credentials,
+    UploadConfig,
+    OrderGroup,
+    CashDeposit,
+    Trade,
+    Holding,
+    Deposit,
+    RateEntry,
+    Dirs,
+)
+from .utils import (
+    load_order_groups,
+    load_cash_deposits,
+    merge_and_sort_groups,
+    fetch_ticker_info,
+    load_rate_file,
+    lookup_rate,
+)
+
+__all__ = [
+    "InsightaClient",
+    "Credentials",
+    "UploadConfig",
+    "OrderGroup",
+    "CashDeposit",
+    "Trade",
+    "Holding",
+    "Deposit",
+    "RateEntry",
+    "Dirs",
+    "load_order_groups",
+    "load_cash_deposits",
+    "merge_and_sort_groups",
+    "fetch_ticker_info",
+    "load_rate_file",
+    "lookup_rate",
+]

insighta_sdk-0.1.0/insighta_sdk/client.py

@@ -0,0 +1,144 @@
+"""Insighta OpenAPI client."""
+
+import json as _json
+import logging
+import os
+
+import requests
+
+from .models import Credentials, OrderGroup, UploadConfig
+
+log = logging.getLogger(__name__)
+
+
+class InsightaClient:
+    """Insighta OpenAPI client."""
+
+    def __init__(self, credentials: Credentials, output_dir: str = "output"):
+        self.endpoint = credentials.endpoint
+        self.output_dir = output_dir
+        self.headers = {
+            "Authorization": f"Bearer {credentials.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        url = f"{self.endpoint}{path}"
+        payload = kwargs.get("json")
+        if payload is not None:
+            self._last_payload = payload
+            payload_str = _json.dumps(payload, indent=2, ensure_ascii=False)
+            log.debug("%s %s\n%s", method, url, payload_str)
+            log_path = os.path.join(self.output_dir, "request_payload.log")
+            with open(log_path, "a", encoding="utf-8") as lf:
+                lf.write(f"=== {method} {url} ===\n{payload_str}\n\n")
+        else:
+            log.debug("%s %s", method, url)
+        resp = requests.request(method, url, headers=self.headers, timeout=30, **kwargs)
+        log.debug("Response %s: %s", resp.status_code, resp.text)
+        resp.raise_for_status()
+        return resp
+
+    def create_portfolio(self, config: UploadConfig) -> str:
+        """POST /portfolios → portfolio_id 반환."""
+        items = [
+            {
+                "ticker": str(item["ticker"]),
+                "type": str(item.get("type", "stock")),
+                "quantity": float(item.get("quantity", 0)),
+                "ratio": float(item.get("ratio", 0)),
+                "price": float(item.get("price", 0)),
+                "sector": str(item.get("sector", "N/A")),
+                "industry": str(item.get("industry", "N/A")),
+            }
+            for item in config.items
+        ]
+        body = {
+            "name": config.name,
+            "description": config.description,
+            "type": config.portfolio_type,
+            "currency": config.currency,
+            "budget": float(config.budget),
+            "target_return": config.target_return,
+            "start_date": config.start_date,
+            "target_date": config.target_date,
+            "items": items,
+        }
+        if config.settings:
+            body["settings"] = config.settings
+        resp = self._request("POST", "/portfolios", json=body)
+        return resp.json()["portfolio_id"]
+
+    def get_portfolios(self) -> list[dict]:
+        """GET /portfolios → return caller's own portfolios."""
+        resp = self._request("GET", "/portfolios")
+        return resp.json()
+
+    def search_portfolios(
+        self,
+        search: str | None = None,
+        country: str | None = None,
+        sort_by: str | None = None,
+        last_item: str | None = None,
+    ) -> dict:
+        """GET /portfolios with search params."""
+        params = {k: v for k, v in {
+            "search": search, "country": country,
+            "sort_by": sort_by, "last_item": last_item,
+        }.items() if v is not None}
+        resp = self._request("GET", "/portfolios", params=params)
+        return resp.json()
+
+    def delete_portfolio(self, portfolio_id: str) -> None:
+        """DELETE /portfolios/{portfolio_id}."""
+        self._request("DELETE", f"/portfolios/{portfolio_id}")
+
+    def get_nav_history(self, portfolio_id: str) -> dict:
+        """GET /portfolios/{portfolio_id}/nav-history."""
+        resp = self._request("GET", f"/portfolios/{portfolio_id}/nav-history")
+        return resp.json()
+
+    def get_metrics_history(
+        self,
+        portfolio_id: str,
+        metrics: str = "twr",
+        from_t: int | None = None,
+        to_t: int | None = None,
+    ) -> dict:
+        """GET /portfolios/{portfolio_id}/metrics-history."""
+        params: dict = {"metrics": metrics}
+        if from_t is not None:
+            params["from_t"] = str(from_t)
+        if to_t is not None:
+            params["to_t"] = str(to_t)
+        resp = self._request(
+            "GET", f"/portfolios/{portfolio_id}/metrics-history",
+            params=params)
+        return resp.json()
+
+    def send_order(self, portfolio_id: str, order_group: OrderGroup, portfolio_currency: str) -> dict:
+        """POST /orders → 주문 그룹 하나 전송."""
+        body = {
+            "portfolio_id": portfolio_id,
+            "currency": portfolio_currency,
+            "payment_currency": order_group.currency,
+            "items": order_group.items,
+        }
+        if order_group.memo:
+            body["memo"] = order_group.memo
+        if order_group.exchange_rate:
+            body["custom_exchange_rate"] = order_group.exchange_rate
+            body["is_custom_exchange_rate"] = True
+        if order_group.cash_deposits:
+            body["cash_deposits"] = [
+                {k: v for k, v in {
+                    "type": d.type,
+                    "amount": d.amount,
+                    "currency": d.currency,
+                    "ticker": d.ticker,
+                    "timestamp": d.timestamp,
+                }.items() if v is not None}
+                for d in order_group.cash_deposits
+            ]
+        resp = self._request("POST", "/orders", json=body)
+        return resp.json() if resp.text else {}

insighta_sdk-0.1.0/insighta_sdk/models.py

@@ -0,0 +1,212 @@
+"""Data models for Insighta SDK."""
+
+import csv
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
+from decimal import Decimal
+
+import yaml
+
+WORKSPACES_DIR = "workspaces"
+JST = timezone(timedelta(hours=9))
+
+
+@dataclass
+class Credentials:
+    api_key: str
+    endpoint: str
+
+    @property
+    def masked_key(self) -> str:
+        if len(self.api_key) <= 8:
+            return "****"
+        return self.api_key[:4] + "****" + self.api_key[-4:]
+
+    @classmethod
+    def from_file(cls, path: str) -> "Credentials":
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        return cls(api_key=data["api_key"], endpoint=data["endpoint"].rstrip("/"))
+
+
+@dataclass
+class UploadConfig:
+    name: str
+    description: str
+    portfolio_type: str
+    currency: str
+    budget: Decimal
+    balance: Decimal
+    order_file: str
+    target_return: float = 0.0
+    start_date: str = ""
+    target_date: str = ""
+    items: list = field(default_factory=list)
+    cash_deposits_file: str | None = None
+    memo_file: str | None = None
+    settings: dict | None = None
+
+    @classmethod
+    def from_file(cls, path: str) -> "UploadConfig":
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        p = data["portfolio"]
+        files = data.get("files", {})
+        return cls(
+            name=p["name"],
+            description=p.get("description", ""),
+            portfolio_type=p["type"],
+            currency=p["currency"],
+            budget=Decimal(str(p["budget"])),
+            balance=Decimal(str(p["budget"])),
+            target_return=float(p.get("target_return", 0)),
+            start_date=p.get("start_date", ""),
+            target_date=p.get("target_date", ""),
+            items=p.get("items", []),
+            order_file=files["order"],
+            cash_deposits_file=files.get("cash_deposits"),
+            memo_file=files.get("memo"),
+            settings=p.get("settings"),
+        )
+
+
+@dataclass
+class CashDeposit:
+    type: str       # budget | dividend
+    amount: float
+    currency: str | None = None
+    ticker: str | None = None
+    timestamp: int | None = None
+
+
+@dataclass
+class OrderGroup:
+    group_id: str
+    currency: str
+    items: list = field(default_factory=list)
+    cash_deposits: list[CashDeposit] = field(default_factory=list)
+    exchange_rate: float | None = None
+    memo: str = ""
+
+
+@dataclass
+class Trade:
+    dt: str          # ISO 8601 JST
+    ticker: str
+    qty: int
+    acct: str
+    price: Decimal
+    avg: Decimal
+    cur: str         # 決済通貨 (JPY or USD)
+    base: str = "USD"  # 銘柄の基準通貨
+
+
+@dataclass
+class Holding:
+    ticker: str
+    acct: str
+    qty: int
+    cost: Decimal = Decimal("0")
+    price: Decimal = Decimal("0")
+    pnl: Decimal = Decimal("0")
+
+
+@dataclass
+class Deposit:
+    dt: str          # ISO 8601 JST or raw datetime
+    amount: Decimal
+    cur: str
+    type: str = "budget"  # budget | dividend
+    ticker: str = ""
+    rate: Decimal | None = None
+
+
+@dataclass
+class RateEntry:
+    start: str
+    end: str
+    pair: str
+    rate: Decimal
+
+
+@dataclass
+class Dirs:
+    """作業ディレクトリ設定。--work オプションで切り替え可能。"""
+    work: str = ""
+
+    @classmethod
+    def from_work(cls, work: str = "") -> "Dirs":
+        return cls(work=work)
+
+    @property
+    def _base(self) -> str:
+        return os.path.join(WORKSPACES_DIR, self.work) if self.work else ""
+
+    @property
+    def input(self) -> str:
+        return os.path.join(self._base, "input") if self._base else "input"
+
+    @property
+    def output(self) -> str:
+        return os.path.join(self._base, "output") if self._base else "output"
+
+    @property
+    def history(self) -> str:
+        return os.path.join(self.input, "history")
+
+    @property
+    def summary(self) -> str:
+        return os.path.join(self.input, "summary")
+
+    @property
+    def seed(self) -> str:
+        return os.path.join(self.input, "seed")
+
+    @property
+    def deposit(self) -> str:
+        return os.path.join(self.input, "deposit")
+
+    @property
+    def exchange(self) -> str:
+        return os.path.join(self.input, "currency_exchange")
+
+    @property
+    def manual(self) -> str:
+        return os.path.join(self.input, "manual")
+
+    @property
+    def rate_csv(self) -> str:
+        return os.path.join(self.input, "rate.csv")
+
+    @property
+    def ratio_csv(self) -> str:
+        return os.path.join(self.input, "ratio.csv")
+
+    @property
+    def history_csv(self) -> str:
+        return os.path.join(self.output, "history.csv")
+
+    @property
+    def order_csv(self) -> str:
+        return os.path.join(self.output, "order.csv")
+
+    @property
+    def upload_yaml(self) -> str:
+        return os.path.join(self.output, "upload.yaml")
+
+    @property
+    def memo_csv(self) -> str:
+        return os.path.join(self.output, "memo.csv")
+
+    @property
+    def cash_deposits_csv(self) -> str:
+        return os.path.join(self.output, "cash_deposits.csv")
+
+    @property
+    def request_payload_log(self) -> str:
+        return os.path.join(self.output, "request_payload.log")
+
+    def ensure_output(self):
+        """output ディレクトリを作成する。"""
+        os.makedirs(self.output, exist_ok=True)

insighta_sdk-0.1.0/insighta_sdk/utils.py

@@ -0,0 +1,148 @@
+"""Utility functions for Insighta SDK."""
+
+import csv
+from collections import OrderedDict
+from datetime import datetime, timezone
+from decimal import Decimal
+
+import requests
+
+from .models import CashDeposit, OrderGroup, RateEntry
+
+
+def _parse_timestamp(val: str) -> int | None:
+    if not val:
+        return None
+    try:
+        return int(val)
+    except ValueError:
+        pass
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M"):
+        try:
+            return int(datetime.strptime(val, fmt).replace(tzinfo=timezone.utc).timestamp() * 1000)
+        except ValueError:
+            continue
+    return None
+
+
+def load_order_groups(filepath: str) -> list[OrderGroup]:
+    """order.csv를 읽어서 group_dt별로 묶어 반환."""
+    groups: OrderedDict[str, OrderGroup] = OrderedDict()
+    with open(filepath, "r", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            gdt = row["group_dt"]
+            rate_val = row.get("rate", "").strip() if row.get("rate") else ""
+            if gdt not in groups:
+                groups[gdt] = OrderGroup(
+                    group_id=gdt,
+                    currency=row.get("settle_currency", row["currency"]),
+                    exchange_rate=float(rate_val) if rate_val else None,
+                )
+            groups[gdt].items.append({
+                "id": row["ticker"],
+                "ticker": row["ticker"],
+                "quantity": float(row["quantity"]),
+                "price": float(row["price"]),
+                "currency": row["currency"],
+                "price_type": row["price_type"],
+                "timestamp": _parse_timestamp(row.get("timestamp", "")),
+            })
+    return list(groups.values())
+
+
+def load_cash_deposits(filepath: str) -> dict[str, list[CashDeposit]]:
+    """cash_deposits.csv를 읽어서 group_dt별로 묶어 반환."""
+    groups: dict[str, list[CashDeposit]] = {}
+    with open(filepath, "r", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            gdt = row["group_dt"]
+            groups.setdefault(gdt, []).append(CashDeposit(
+                type=row["type"],
+                amount=float(row["amount"]),
+                currency=row.get("currency") or None,
+                ticker=row.get("ticker") or None,
+                timestamp=_parse_timestamp(row.get("timestamp", "")),
+            ))
+    return groups
+
+
+def merge_and_sort_groups(
+    orders: list[OrderGroup],
+    deposits_by_gdt: dict[str, list[CashDeposit]],
+    memos: dict[str, str],
+) -> list[OrderGroup]:
+    """order + deposit을 group_dt 기준으로 머지하고 시간순 정렬."""
+    existing_gdts = {g.group_id for g in orders}
+    for gdt, deps in deposits_by_gdt.items():
+        if gdt not in existing_gdts:
+            cur = deps[0].currency or "USD"
+            orders.append(OrderGroup(group_id=gdt, currency=cur))
+    deps_map = dict(deposits_by_gdt)
+    for g in orders:
+        if g.group_id in deps_map:
+            g.cash_deposits = deps_map[g.group_id]
+
+    def _sort_key(g: OrderGroup):
+        ts = _parse_timestamp(g.group_id)
+        return ts if ts is not None else float("inf")
+    orders.sort(key=_sort_key)
+    for i, g in enumerate(orders, 1):
+        g.group_id = str(i)
+    for g in orders:
+        if g.group_id in memos:
+            g.memo = memos[g.group_id]
+    return orders
+
+
+def fetch_ticker_info(tickers: list[str]) -> dict[str, dict]:
+    """Insighta /tickers/info API로 sector/industry/type 조회."""
+    if not tickers:
+        return {}
+    resp = requests.get(
+        "https://api.insighta.cloud/tickers/info",
+        params={"tickers": ",".join(tickers), "conditions": "sector,industry,type"},
+        timeout=10,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def load_rate_file(filepath: str) -> list[RateEntry]:
+    """為替レートCSVを読み込む。
+
+    CSV format:
+        from,to,pair,rate
+        2024/01/01,2024/12/31,USD/JPY,155.50
+    """
+    entries: list[RateEntry] = []
+    with open(filepath, "r", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            entries.append(RateEntry(
+                start=row["from"].strip(),
+                end=row["to"].strip(),
+                pair=row["pair"].strip(),
+                rate=Decimal(row["rate"].strip()),
+            ))
+    return entries
+
+
+def _normalize_dt(val: str) -> str:
+    return val if " " in val else f"{val} 00:00"
+
+
+def _normalize_dt_end(val: str) -> str:
+    return val if " " in val else f"{val} 23:59"
+
+
+def lookup_rate(entries: list[RateEntry], dt: str, cur: str, base: str) -> Decimal | None:
+    """決済通貨と基準通貨が異なる場合のみ該当期間のレートを返す。"""
+    if cur == base:
+        return None
+    trade_dt = dt[:16].replace("-", "/").replace("T", " ") if dt else ""
+    pair = f"{base}/{cur}"
+    for e in entries:
+        start = _normalize_dt(e.start)
+        end = _normalize_dt_end(e.end)
+        if e.pair == pair and start <= trade_dt <= end:
+            return e.rate
+    return None

insighta_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "insighta-sdk"
+version = "0.1.0"
+description = "Insighta Cloud SDK - API client and data models"
+readme = "README.md"
+license = "CC-BY-NC-4.0"
+requires-python = ">=3.10"
+authors = [{ name = "insighta cloud Inc." }]
+keywords = ["insighta", "portfolio", "investment", "sdk", "api-client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://insighta.cloud"
+
+[tool.hatch.build.targets.wheel]
+packages = ["insighta_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

insighta_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,197 @@
+"""Tests for insighta_sdk.client (InsightaClient)."""
+
+import json
+import os
+from decimal import Decimal
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from insighta_sdk.client import InsightaClient
+from insighta_sdk.models import CashDeposit, Credentials, OrderGroup, UploadConfig
+
+
+@pytest.fixture
+def creds():
+    return Credentials(api_key="sk-test-12345678", endpoint="https://api.example.com")
+
+
+@pytest.fixture
+def client(creds, tmp_path):
+    return InsightaClient(creds, output_dir=str(tmp_path))
+
+
+class TestInit:
+    def test_headers(self, client):
+        assert client.headers["Authorization"] == "Bearer sk-test-12345678"
+        assert client.headers["Content-Type"] == "application/json"
+
+    def test_endpoint(self, client):
+        assert client.endpoint == "https://api.example.com"
+
+
+class TestRequest:
+    @patch("insighta_sdk.client.requests.request")
+    def test_get(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.text = '[]'
+        mock_resp.json.return_value = []
+        mock_req.return_value = mock_resp
+
+        resp = client._request("GET", "/portfolios")
+        mock_req.assert_called_once_with(
+            "GET", "https://api.example.com/portfolios",
+            headers=client.headers, timeout=30,
+        )
+        assert resp.json() == []
+
+    @patch("insighta_sdk.client.requests.request")
+    def test_post_logs_payload(self, mock_req, client, tmp_path):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.text = '{"id": "123"}'
+        mock_resp.json.return_value = {"id": "123"}
+        mock_req.return_value = mock_resp
+
+        client._request("POST", "/test", json={"key": "value"})
+        log_path = os.path.join(str(tmp_path), "request_payload.log")
+        assert os.path.exists(log_path)
+        content = open(log_path).read()
+        assert '"key": "value"' in content
+
+
+class TestCreatePortfolio:
+    @patch("insighta_sdk.client.requests.request")
+    def test_create(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 201
+        mock_resp.text = '{"portfolio_id": "pf-123"}'
+        mock_resp.json.return_value = {"portfolio_id": "pf-123"}
+        mock_req.return_value = mock_resp
+
+        config = UploadConfig(
+            name="Test", description="", portfolio_type="record",
+            currency="USD", budget=Decimal("10000"), balance=Decimal("10000"),
+            order_file="order.csv", items=[{"ticker": "SPY", "type": "stock", "quantity": 10, "ratio": 1.0, "price": 0, "sector": "N/A", "industry": "N/A"}],
+        )
+        pid = client.create_portfolio(config)
+        assert pid == "pf-123"
+        call_kwargs = mock_req.call_args[1]
+        body = call_kwargs["json"]
+        assert body["name"] == "Test"
+        assert body["budget"] == 10000.0
+
+
+class TestGetPortfolios:
+    @patch("insighta_sdk.client.requests.request")
+    def test_get(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.text = '[{"portfolio_id": "pf-1", "name": "A"}]'
+        mock_resp.json.return_value = [{"portfolio_id": "pf-1", "name": "A"}]
+        mock_req.return_value = mock_resp
+
+        result = client.get_portfolios()
+        assert len(result) == 1
+        assert result[0]["name"] == "A"
+
+
+class TestSearchPortfolios:
+    @patch("insighta_sdk.client.requests.request")
+    def test_search(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"items": []}
+        mock_resp.status_code = 200
+        mock_resp.text = '{}'
+        mock_req.return_value = mock_resp
+
+        result = client.search_portfolios(search="tech", country="US")
+        call_kwargs = mock_req.call_args[1]
+        assert call_kwargs["params"]["search"] == "tech"
+        assert call_kwargs["params"]["country"] == "US"
+
+
+class TestDeletePortfolio:
+    @patch("insighta_sdk.client.requests.request")
+    def test_delete(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 204
+        mock_resp.text = ''
+        mock_req.return_value = mock_resp
+
+        client.delete_portfolio("pf-123")
+        mock_req.assert_called_once()
+        assert "/portfolios/pf-123" in mock_req.call_args[0][1]
+
+
+class TestSendOrder:
+    @patch("insighta_sdk.client.requests.request")
+    def test_basic_order(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.text = '{"order_id": "o-1"}'
+        mock_resp.json.return_value = {"order_id": "o-1"}
+        mock_req.return_value = mock_resp
+
+        group = OrderGroup(
+            group_id="1", currency="USD",
+            items=[{"ticker": "AAPL", "quantity": 5, "price": 150.0}],
+        )
+        result = client.send_order("pf-123", group, "USD")
+        assert result["order_id"] == "o-1"
+        body = mock_req.call_args[1]["json"]
+        assert body["portfolio_id"] == "pf-123"
+        assert body["payment_currency"] == "USD"
+
+    @patch("insighta_sdk.client.requests.request")
+    def test_order_with_deposits_and_rate(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.text = '{}'
+        mock_resp.json.return_value = {}
+        mock_req.return_value = mock_resp
+
+        group = OrderGroup(
+            group_id="1", currency="JPY",
+            items=[{"ticker": "AAPL", "quantity": 5, "price": 150.0}],
+            cash_deposits=[CashDeposit(type="budget", amount=100000.0, currency="JPY")],
+            exchange_rate=155.0,
+            memo="test memo",
+        )
+        client.send_order("pf-123", group, "USD")
+        body = mock_req.call_args[1]["json"]
+        assert body["custom_exchange_rate"] == 155.0
+        assert body["is_custom_exchange_rate"] is True
+        assert body["memo"] == "test memo"
+        assert len(body["cash_deposits"]) == 1
+        assert body["cash_deposits"][0]["amount"] == 100000.0
+
+
+class TestGetNavHistory:
+    @patch("insighta_sdk.client.requests.request")
+    def test_nav(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"history": [{"date": "2024-01-01", "nav": 10000}]}
+        mock_resp.status_code = 200
+        mock_resp.text = '{}'
+        mock_req.return_value = mock_resp
+
+        result = client.get_nav_history("pf-123")
+        assert "history" in result
+
+
+class TestGetMetricsHistory:
+    @patch("insighta_sdk.client.requests.request")
+    def test_metrics(self, mock_req, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"history": []}
+        mock_resp.status_code = 200
+        mock_resp.text = '{}'
+        mock_req.return_value = mock_resp
+
+        result = client.get_metrics_history("pf-123", metrics="twr", from_t=1000, to_t=2000)
+        params = mock_req.call_args[1]["params"]
+        assert params["metrics"] == "twr"
+        assert params["from_t"] == "1000"
+        assert params["to_t"] == "2000"

insighta_sdk-0.1.0/tests/test_models.py

@@ -0,0 +1,124 @@
+"""Tests for insighta_sdk.models."""
+
+import os
+import tempfile
+from decimal import Decimal
+
+import pytest
+import yaml
+
+from insighta_sdk.models import (
+    Credentials,
+    Deposit,
+    Dirs,
+    Holding,
+    RateEntry,
+    Trade,
+    UploadConfig,
+)
+
+
+class TestDirs:
+    def test_from_work_empty(self):
+        d = Dirs.from_work("")
+        assert d._base == ""
+        assert d.input == "input"
+        assert d.output == "output"
+
+    def test_from_work_named(self):
+        d = Dirs.from_work("my-portfolio")
+        assert d._base == "workspaces/my-portfolio"
+        assert d.input == "workspaces/my-portfolio/input"
+        assert d.output == "workspaces/my-portfolio/output"
+        assert d.history_csv == "workspaces/my-portfolio/output/history.csv"
+        assert d.rate_csv == "workspaces/my-portfolio/input/rate.csv"
+
+    def test_ensure_output(self, tmp_path):
+        d = Dirs(work="")
+        d_output = str(tmp_path / "out")
+        # monkey-patch output property
+        Dirs.output = property(lambda self: d_output)
+        d.ensure_output()
+        assert os.path.isdir(d_output)
+        # restore
+        Dirs.output = property(lambda self: os.path.join(self._base, "output") if self._base else "output")
+
+    def test_all_paths(self):
+        d = Dirs.from_work("test")
+        assert "seed" in d.seed
+        assert "deposit" in d.deposit
+        assert "manual" in d.manual
+        assert "order.csv" in d.order_csv
+        assert "upload.yaml" in d.upload_yaml
+        assert "memo.csv" in d.memo_csv
+
+
+class TestCredentials:
+    def test_from_file(self, tmp_path):
+        cred_file = tmp_path / "creds.yaml"
+        cred_file.write_text(yaml.dump({"api_key": "sk-test-12345678", "endpoint": "https://api.example.com/"}))
+        c = Credentials.from_file(str(cred_file))
+        assert c.api_key == "sk-test-12345678"
+        assert c.endpoint == "https://api.example.com"  # trailing slash stripped
+
+    def test_masked_key_long(self):
+        c = Credentials(api_key="sk-test-12345678", endpoint="")
+        assert c.masked_key == "sk-t****5678"
+
+    def test_masked_key_short(self):
+        c = Credentials(api_key="short", endpoint="")
+        assert c.masked_key == "****"
+
+
+class TestUploadConfig:
+    def test_from_file(self, tmp_path):
+        config = {
+            "portfolio": {
+                "name": "Test",
+                "description": "desc",
+                "type": "record",
+                "currency": "USD",
+                "budget": 10000,
+                "target_return": 0.1,
+                "start_date": "2024-01-01",
+                "target_date": "2034-01-01",
+                "items": [{"ticker": "SPY", "ratio": 1.0}],
+            },
+            "files": {"order": "order.csv", "cash_deposits": "deposits.csv"},
+        }
+        f = tmp_path / "upload.yaml"
+        f.write_text(yaml.dump(config))
+        uc = UploadConfig.from_file(str(f))
+        assert uc.name == "Test"
+        assert uc.budget == Decimal("10000")
+        assert uc.order_file == "order.csv"
+        assert uc.cash_deposits_file == "deposits.csv"
+        assert uc.items == [{"ticker": "SPY", "ratio": 1.0}]
+
+
+class TestTrade:
+    def test_creation(self):
+        t = Trade(dt="2024-01-01T10:00:00+09:00", ticker="AAPL", qty=10,
+                  acct="TT", price=Decimal("150.5"), avg=Decimal("150.5"), cur="USD")
+        assert t.base == "USD"
+        assert t.qty == 10
+
+
+class TestHolding:
+    def test_defaults(self):
+        h = Holding(ticker="MSFT", acct="NISA", qty=5)
+        assert h.cost == Decimal("0")
+        assert h.pnl == Decimal("0")
+
+
+class TestDeposit:
+    def test_creation(self):
+        d = Deposit(dt="2024-01-01", amount=Decimal("1000"), cur="JPY", type="budget")
+        assert d.ticker == ""
+        assert d.rate is None
+
+
+class TestRateEntry:
+    def test_creation(self):
+        r = RateEntry(start="2024/01/01", end="2024/12/31", pair="USD/JPY", rate=Decimal("155.5"))
+        assert r.pair == "USD/JPY"

insighta_sdk-0.1.0/tests/test_utils.py

@@ -0,0 +1,135 @@
+"""Tests for insighta_sdk.utils."""
+
+import csv
+import os
+from decimal import Decimal
+
+import pytest
+
+from insighta_sdk.models import CashDeposit, OrderGroup, RateEntry
+from insighta_sdk.utils import (
+    _parse_timestamp,
+    load_cash_deposits,
+    load_order_groups,
+    load_rate_file,
+    lookup_rate,
+    merge_and_sort_groups,
+)
+
+
+class TestParseTimestamp:
+    def test_integer_string(self):
+        assert _parse_timestamp("1700000000000") == 1700000000000
+
+    def test_datetime_string(self):
+        ts = _parse_timestamp("2024-01-01 00:00:00")
+        assert ts == 1704067200000
+
+    def test_empty(self):
+        assert _parse_timestamp("") is None
+
+    def test_invalid(self):
+        assert _parse_timestamp("not-a-date") is None
+
+
+class TestLoadRateFile:
+    def test_load(self, tmp_path):
+        f = tmp_path / "rate.csv"
+        f.write_text("from,to,pair,rate\n2024/01/01,2024/06/30,USD/JPY,150.00\n2024/07/01,2024/12/31,USD/JPY,155.50\n")
+        entries = load_rate_file(str(f))
+        assert len(entries) == 2
+        assert entries[0].pair == "USD/JPY"
+        assert entries[0].rate == Decimal("150.00")
+        assert entries[1].rate == Decimal("155.50")
+
+
+class TestLookupRate:
+    @pytest.fixture
+    def rates(self):
+        return [
+            RateEntry(start="2024/01/01", end="2024/06/30", pair="USD/JPY", rate=Decimal("150")),
+            RateEntry(start="2024/07/01", end="2024/12/31", pair="USD/JPY", rate=Decimal("155")),
+        ]
+
+    def test_match_first_period(self, rates):
+        r = lookup_rate(rates, "2024-03-15T10:00:00+09:00", "JPY", "USD")
+        assert r == Decimal("150")
+
+    def test_match_second_period(self, rates):
+        r = lookup_rate(rates, "2024-08-01T10:00:00+09:00", "JPY", "USD")
+        assert r == Decimal("155")
+
+    def test_same_currency_returns_none(self, rates):
+        r = lookup_rate(rates, "2024-03-15T10:00:00+09:00", "USD", "USD")
+        assert r is None
+
+    def test_no_match_returns_none(self, rates):
+        r = lookup_rate(rates, "2025-01-01T10:00:00+09:00", "JPY", "USD")
+        assert r is None
+
+    def test_date_only_format(self, rates):
+        r = lookup_rate(rates, "2024-01-15", "JPY", "USD")
+        assert r == Decimal("150")
+
+
+class TestLoadOrderGroups:
+    def test_load(self, tmp_path):
+        f = tmp_path / "order.csv"
+        f.write_text(
+            "group_dt,ticker,quantity,price,currency,settle_currency,rate,price_type,timestamp\n"
+            "2024-01-01 10:00:00,AAPL,5,150.0,USD,USD,,LIMIT,2024-01-01 01:00:00\n"
+            "2024-01-01 10:00:00,MSFT,3,300.0,USD,USD,,LIMIT,2024-01-01 01:00:00\n"
+            "2024-01-02 10:00:00,GOOG,2,140.0,USD,JPY,155.0,LIMIT,2024-01-02 01:00:00\n"
+        )
+        groups = load_order_groups(str(f))
+        assert len(groups) == 2
+        assert groups[0].group_id == "2024-01-01 10:00:00"
+        assert len(groups[0].items) == 2
+        assert groups[0].items[0]["ticker"] == "AAPL"
+        assert groups[1].exchange_rate == 155.0
+
+    def test_empty_file(self, tmp_path):
+        f = tmp_path / "order.csv"
+        f.write_text("group_dt,ticker,quantity,price,currency,settle_currency,rate,price_type,timestamp\n")
+        groups = load_order_groups(str(f))
+        assert groups == []
+
+
+class TestLoadCashDeposits:
+    def test_load(self, tmp_path):
+        f = tmp_path / "deposits.csv"
+        f.write_text(
+            "group_dt,type,amount,currency,ticker,timestamp\n"
+            "2024-01-01 00:00:00,budget,5000.0,USD,,2024-01-01 00:00:00\n"
+            "2024-01-01 00:00:00,dividend,50.0,USD,AAPL,2024-01-01 00:00:00\n"
+            "2024-01-02 00:00:00,budget,3000.0,JPY,,2024-01-02 00:00:00\n"
+        )
+        groups = load_cash_deposits(str(f))
+        assert len(groups) == 2
+        assert len(groups["2024-01-01 00:00:00"]) == 2
+        assert groups["2024-01-01 00:00:00"][0].type == "budget"
+        assert groups["2024-01-01 00:00:00"][1].ticker == "AAPL"
+
+
+class TestMergeAndSortGroups:
+    def test_merge_basic(self):
+        orders = [
+            OrderGroup(group_id="1704067200000", currency="USD", items=[{"ticker": "AAPL"}]),
+        ]
+        deposits = {
+            "1704067200000": [CashDeposit(type="budget", amount=5000.0, currency="USD")],
+            "1704153600000": [CashDeposit(type="budget", amount=3000.0, currency="JPY")],
+        }
+        result = merge_and_sort_groups(orders, deposits, {"1": "first memo"})
+        assert len(result) == 2
+        # 정렬 후 순번 재배정
+        assert result[0].group_id == "1"
+        assert result[1].group_id == "2"
+        # deposit 붙었는지
+        assert len(result[0].cash_deposits) == 1
+        # memo 적용
+        assert result[0].memo == "first memo"
+
+    def test_empty(self):
+        result = merge_and_sort_groups([], {}, {})
+        assert result == []