finlet 0.0.1__py3-none-any.whl

finlet/cli.py

@@ -0,0 +1,213 @@
+"""CLI entrypoint — finlet serve / session / plugins / mcp."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import typer
+
+from finlet.config import PLUGINS_CONFIG_PATH
+
+_API_URL = os.environ.get("FINLET_API_URL", "https://finlet.dev")
+
+
+def _api_headers(api_key: str | None) -> dict[str, str]:
+    """Build request headers, including Bearer auth if an API key is provided."""
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+app = typer.Typer(
+    name="finlet",
+    help="Finlet — Integrated Testing Environment for AI Trading Agent Reasoning",
+    no_args_is_help=True,
+)
+
+session_app = typer.Typer(help="Session management")
+plugins_app = typer.Typer(help="Plugin management")
+app.add_typer(session_app, name="session")
+app.add_typer(plugins_app, name="plugins")
+
+
+# ── serve ────────────────────────────────────────────────────
+
+
+@app.command()
+def serve(
+    host: str = typer.Option("0.0.0.0", envvar="FINLET_HOST", help="Bind address"),
+    port: int = typer.Option(8000, envvar="FINLET_PORT", help="Port number"),
+    reload: bool = typer.Option(False, help="Enable auto-reload for development"),
+) -> None:
+    """Start the API server and serve the dashboard."""
+    try:
+        import uvicorn
+    except ImportError:
+        typer.echo("Error: Server mode requires the full Finlet installation.", err=True)
+        typer.echo("Install with: pip install finlet[server]", err=True)
+        raise typer.Exit(1)
+
+    uvicorn.run(
+        "finlet.api.app:create_app",
+        factory=True,
+        host=host,
+        port=port,
+        reload=reload,
+    )
+
+
+# ── session ──────────────────────────────────────────────────
+
+
+@session_app.command("create")
+def session_create(
+    name: str = typer.Option(..., "--name", "-n", help="Session name"),
+    start: str = typer.Option(..., "--start", "-s", help="Start datetime (ISO format, e.g. 2024-01-01)"),
+    capital: float = typer.Option(100_000.0, "--capital", "-c", help="Initial capital"),
+    universe: str = typer.Option("", "--universe", "-u", help="Comma-separated ticker symbols"),
+    api_key: str | None = typer.Option(
+        None, "--api-key", "-k", envvar="FINLET_API_KEY", help="API key for authentication"
+    ),
+) -> None:
+    """Create a new simulation session."""
+    import httpx
+
+    tickers = [t.strip() for t in universe.split(",") if t.strip()] if universe else []
+    body = {
+        "name": name,
+        "start_time": start,
+        "initial_capital": capital,
+        "universe": tickers,
+    }
+
+    try:
+        resp = httpx.post(f"{_API_URL}/sessions", json=body, headers=_api_headers(api_key), timeout=10)
+        resp.raise_for_status()
+        data = resp.json()
+        typer.echo(f"Session created: {data['id']} ({data['name']})")
+        typer.echo(f"  Start: {data['config']['start_time']}")
+        typer.echo(f"  Capital: ${data['config']['initial_capital']:,.2f}")
+        if tickers:
+            typer.echo(f"  Universe: {', '.join(tickers)}")
+    except httpx.ConnectError:
+        typer.echo("Error: Cannot connect to Finlet server. Run 'finlet serve' first.", err=True)
+        raise typer.Exit(1)
+    except httpx.HTTPStatusError as e:
+        typer.echo(f"Error: {e.response.json().get('detail', str(e))}", err=True)
+        raise typer.Exit(1)
+
+
+@session_app.command("list")
+def session_list(
+    api_key: str | None = typer.Option(
+        None, "--api-key", "-k", envvar="FINLET_API_KEY", help="API key for authentication"
+    ),
+) -> None:
+    """List all sessions."""
+    import httpx
+
+    try:
+        resp = httpx.get(f"{_API_URL}/sessions", headers=_api_headers(api_key), timeout=10)
+        resp.raise_for_status()
+        sessions = resp.json()
+        if not sessions:
+            typer.echo("No active sessions.")
+            return
+        for s in sessions:
+            clock_time = s.get("clock", {}).get("current_time", "unknown")
+            typer.echo(f"  {s['id']}  {s.get('name', s['id'])}  [{s['status']}]  {clock_time}")
+    except httpx.ConnectError:
+        typer.echo("Error: Cannot connect to Finlet server. Run 'finlet serve' first.", err=True)
+        raise typer.Exit(1)
+
+
+@session_app.command("delete")
+def session_delete(
+    session_id: str = typer.Argument(..., help="Session ID to delete"),
+    api_key: str | None = typer.Option(
+        None, "--api-key", "-k", envvar="FINLET_API_KEY", help="API key for authentication"
+    ),
+) -> None:
+    """Delete a session."""
+    import httpx
+
+    try:
+        resp = httpx.delete(f"{_API_URL}/sessions/{session_id}", headers=_api_headers(api_key), timeout=10)
+        if resp.status_code == 404:
+            typer.echo(f"Error: Session '{session_id}' not found.", err=True)
+            raise typer.Exit(1)
+        resp.raise_for_status()
+        typer.echo(f"Session deleted: {session_id}")
+    except httpx.ConnectError:
+        typer.echo("Error: Cannot connect to Finlet server. Run 'finlet serve' first.", err=True)
+        raise typer.Exit(1)
+    except httpx.HTTPStatusError as e:
+        typer.echo(f"Error: {e.response.json().get('detail', str(e))}", err=True)
+        raise typer.Exit(1)
+
+
+# ── plugins ──────────────────────────────────────────────────
+
+
+def _load_plugins_config() -> dict:  # type: ignore[type-arg]
+    if PLUGINS_CONFIG_PATH.exists():
+        return json.loads(PLUGINS_CONFIG_PATH.read_text())  # type: ignore[no-any-return]
+    return {}
+
+
+def _save_plugins_config(config: dict) -> None:
+    PLUGINS_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    PLUGINS_CONFIG_PATH.write_text(json.dumps(config, indent=2) + "\n")
+
+
+@plugins_app.command("list")
+def plugins_list() -> None:
+    """Show installed plugins and status."""
+    config = _load_plugins_config()
+    builtin = {
+        "price": {"type": "price", "requires_key": False},
+        "edgar": {"type": "filings", "requires_key": False},
+        "fred": {"type": "economic", "requires_key": True},
+        "finnhub": {"type": "news+fundamentals", "requires_key": True},
+    }
+    typer.echo("Plugins:")
+    for name, info in builtin.items():
+        status = "configured" if name in config else ("ready" if not info["requires_key"] else "needs API key")
+        typer.echo(f"  {name:12s}  [{info['type']:20s}]  {status}")
+
+
+@plugins_app.command("add")
+def plugins_add(
+    name: str = typer.Argument(..., help="Plugin name (e.g. 'finnhub', 'fred')"),
+    api_key: str | None = typer.Option(None, "--api-key", "-k", help="API key"),
+    email: str | None = typer.Option(None, "--email", "-e", help="Email (for EDGAR User-Agent)"),
+) -> None:
+    """Configure a plugin with API key or settings."""
+    config = _load_plugins_config()
+    entry: dict[str, str] = {"enabled": "true"}
+    if api_key:
+        entry["api_key"] = api_key
+    if email:
+        entry["email"] = email
+    config[name] = entry
+    _save_plugins_config(config)
+    typer.echo(f"Plugin '{name}' configured. Restart server to apply.")
+
+
+# ── mcp ──────────────────────────────────────────────────────
+
+
+@app.command()
+def mcp() -> None:
+    """Start MCP server over stdio (for Claude Code integration)."""
+    try:
+        from finlet.mcp.server import mcp as mcp_server
+    except ImportError:
+        typer.echo("Error: Local MCP server requires the full Finlet installation.", err=True)
+        typer.echo("Use MCP-over-HTTP with finlet.dev instead.", err=True)
+        typer.echo("Install server with: pip install finlet[server]", err=True)
+        raise typer.Exit(1)
+
+    mcp_server.run(transport="stdio")

finlet/config.py

@@ -0,0 +1,187 @@
+"""Centralized configuration for Finlet.
+
+All environment variable access is consolidated here. Modules import
+from ``finlet.config`` instead of calling ``os.environ`` / ``os.getenv``
+directly.
+
+Variables that need SSM resolution (secrets) still go through ``finlet.ssm``
+and are not duplicated here — this module handles non-secret configuration
+only.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ── Filesystem paths (single source of truth) ────────────────
+FINLET_DIR = Path.home() / ".finlet"
+PLUGINS_CONFIG_PATH = FINLET_DIR / "plugins.json"
+
+
+@dataclass(frozen=True, slots=True)
+class LoggingConfig:
+    """Logging settings."""
+
+    format: str = os.environ.get("FINLET_LOG_FORMAT", "json").lower()
+    level: str = os.environ.get("FINLET_LOG_LEVEL", "INFO").upper()
+
+
+@dataclass(frozen=True, slots=True)
+class CORSConfig:
+    """CORS settings."""
+
+    origins_raw: str = os.environ.get("FINLET_CORS_ORIGINS", "").strip()
+
+
+@dataclass(frozen=True, slots=True)
+class SecurityConfig:
+    """Security middleware settings."""
+
+    max_request_body_bytes: int = int(os.environ.get("FINLET_MAX_REQUEST_BODY_BYTES", str(1024 * 1024)))
+    hsts_enabled: bool = os.environ.get("FINLET_HSTS_ENABLED", "").lower() in (
+        "true",
+        "1",
+        "yes",
+    )
+    key_rotation_grace_hours: int = int(os.environ.get("FINLET_KEY_ROTATION_GRACE_HOURS", "24"))
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimitConfig:
+    """Rate limiting settings."""
+
+    reset_max_per_hour: int = int(os.environ.get("FINLET_RESET_RATE_LIMIT", "5"))
+    market_data_max_per_hour: int = int(os.environ.get("FINLET_MARKET_DATA_RATE_LIMIT", "100"))
+    trade_max_per_hour: int = int(os.environ.get("FINLET_TRADE_RATE_LIMIT", "50"))
+    plugin_rate_per_user_per_minute: int = int(os.environ.get("FINLET_PLUGIN_RATE_PER_USER", "30"))
+    plugin_rate_global_per_minute: int = int(os.environ.get("FINLET_PLUGIN_RATE_GLOBAL", "150"))
+
+
+@dataclass(frozen=True, slots=True)
+class BillingConfig:
+    """Billing redirect settings."""
+
+    _allowed_raw: str = os.environ.get("FINLET_ALLOWED_REDIRECT_DOMAINS", "").strip()
+    _default_domains: tuple[str, ...] = ("finlet.dev", "localhost")
+
+    @property
+    def allowed_redirect_domains(self) -> list[str]:
+        parsed = [d.strip() for d in self._allowed_raw.split(",") if d.strip()]
+        return parsed or list(self._default_domains)
+
+
+@dataclass(frozen=True, slots=True)
+class AdminConfig:
+    """Admin user settings."""
+
+    admin_user_ids_raw: str = os.environ.get("FINLET_ADMIN_USER_IDS", "").strip()
+
+    @property
+    def admin_user_ids(self) -> set[str]:
+        if not self.admin_user_ids_raw:
+            return set()
+        return {uid.strip() for uid in self.admin_user_ids_raw.split(",") if uid.strip()}
+
+
+@dataclass(frozen=True, slots=True)
+class MarketplaceConfig:
+    """Marketplace feature flag."""
+
+    enabled: bool = os.environ.get("FINLET_MARKETPLACE_ENABLED", "").lower() in (
+        "true",
+        "1",
+        "yes",
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class SSMConfig:
+    """AWS SSM Parameter Store settings."""
+
+    enabled: bool = os.environ.get("FINLET_SSM_ENABLED", "1") != "0"
+    prefix: str = os.environ.get("FINLET_SSM_PREFIX", "/finlet/prod")
+    region: str = os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+
+
+@dataclass(frozen=True, slots=True)
+class PricePluginConfig:
+    """Price plugin settings."""
+
+    bucket: str = os.environ.get("FINLET_PRICE_BUCKET", "finlet-data")
+
+
+@dataclass(frozen=True, slots=True)
+class FundamentalsPluginConfig:
+    """Fundamentals plugin settings."""
+
+    bucket: str = os.environ.get("FINLET_PRICE_BUCKET", "finlet-data")
+    prefix: str = os.environ.get("FINLET_FUNDAMENTALS_PREFIX", "fundamentals/quarterly")
+
+
+@dataclass(frozen=True, slots=True)
+class NewsPluginConfig:
+    """News plugin settings."""
+
+    bucket: str = os.environ.get("FINLET_PRICE_BUCKET", "finlet-data")
+    prefix: str = os.environ.get("FINLET_NEWS_PREFIX", "news/daily")
+
+
+@dataclass(frozen=True, slots=True)
+class SentimentPluginConfig:
+    """Sentiment plugin settings.
+
+    S3 path layout: sentiment/analyst_ratings/{TICKER}.parquet
+
+    Schema per row:
+        ticker:             str          — ticker symbol
+        rated_at:           datetime UTC — rating issue date (ceiling-filtered)
+        firm:               str          — analyst firm name
+        action:             str          — Upgrade | Downgrade | Reiterated | Initiated | Maintains | Resumed
+        from_grade:         str | None   — prior grade
+        to_grade:           str | None   — new grade
+        price_target_from:  float | None — prior price target
+        price_target_to:    float | None — new price target
+        source:             str          — scraper source (e.g. "stockanalysis")
+        ingested_at:        datetime UTC — ingestion timestamp
+    """
+
+    bucket: str = os.environ.get("FINLET_PRICE_BUCKET", "finlet-data")
+    prefix: str = os.environ.get("FINLET_SENTIMENT_PREFIX", "sentiment/analyst_ratings")
+
+
+@dataclass(frozen=True, slots=True)
+class SessionAuthConfig:
+    """Session authentication settings."""
+
+    expiry_hours: int = 24
+    token_bytes: int = 32
+    csrf_token_bytes: int = 32
+    cookie_name: str = "finlet_session"
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Top-level settings container.
+
+    Instantiate once at import time. All sub-configs read from environment
+    variables at construction time.
+    """
+
+    logging: LoggingConfig = field(default_factory=LoggingConfig)
+    cors: CORSConfig = field(default_factory=CORSConfig)
+    security: SecurityConfig = field(default_factory=SecurityConfig)
+    rate_limit: RateLimitConfig = field(default_factory=RateLimitConfig)
+    billing: BillingConfig = field(default_factory=BillingConfig)
+    admin: AdminConfig = field(default_factory=AdminConfig)
+    marketplace: MarketplaceConfig = field(default_factory=MarketplaceConfig)
+    ssm: SSMConfig = field(default_factory=SSMConfig)
+    price_plugin: PricePluginConfig = field(default_factory=PricePluginConfig)
+    fundamentals_plugin: FundamentalsPluginConfig = field(default_factory=FundamentalsPluginConfig)
+    news_plugin: NewsPluginConfig = field(default_factory=NewsPluginConfig)
+    sentiment_plugin: SentimentPluginConfig = field(default_factory=SentimentPluginConfig)
+    session_auth: SessionAuthConfig = field(default_factory=SessionAuthConfig)
+
+
+settings = Settings()

finlet-0.0.1.dist-info/METADATA

@@ -0,0 +1,453 @@
+Metadata-Version: 2.4
+Name: finlet
+Version: 0.0.1
+Summary: A historical market simulation environment for testing AI trading agent reasoning against real market data.
+Author: Finlet Contributors
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Keywords: agent,ai,backtesting,llm,mcp,simulation,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy-boto3-s3>=1.34; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-markdown>=3.6; extra == 'dev'
+Provides-Extra: ingest
+Requires-Dist: beautifulsoup4>=4.12; extra == 'ingest'
+Requires-Dist: boto3>=1.34; extra == 'ingest'
+Requires-Dist: curl-cffi>=0.15.0; extra == 'ingest'
+Requires-Dist: httpx>=0.27; extra == 'ingest'
+Requires-Dist: pandas>=2.0; extra == 'ingest'
+Requires-Dist: pyarrow>=15.0; extra == 'ingest'
+Requires-Dist: structlog>=24.1; extra == 'ingest'
+Requires-Dist: tenacity>=8.2; extra == 'ingest'
+Requires-Dist: yfinance>=0.2.36; extra == 'ingest'
+Provides-Extra: server
+Requires-Dist: aiosqlite>=0.20; extra == 'server'
+Requires-Dist: alembic>=1.14; extra == 'server'
+Requires-Dist: argon2-cffi>=23.1.0; extra == 'server'
+Requires-Dist: boto3>=1.34; extra == 'server'
+Requires-Dist: cryptography>=46.0.6; extra == 'server'
+Requires-Dist: edgartools>=3.0; extra == 'server'
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: finnhub-python>=2.4; extra == 'server'
+Requires-Dist: fredapi>=0.5; extra == 'server'
+Requires-Dist: greenlet>=3.0; extra == 'server'
+Requires-Dist: markdown>=3.6; extra == 'server'
+Requires-Dist: mcp>=1.2; extra == 'server'
+Requires-Dist: pyarrow>=15.0; extra == 'server'
+Requires-Dist: pydantic[email]>=2.9; extra == 'server'
+Requires-Dist: pyotp>=2.9; extra == 'server'
+Requires-Dist: qrcode[pil]>=7.4; extra == 'server'
+Requires-Dist: sqlmodel>=0.0.22; extra == 'server'
+Requires-Dist: stripe>=8.0; extra == 'server'
+Requires-Dist: structlog>=24.1; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'server'
+Provides-Extra: sms
+Requires-Dist: twilio>=9.0; extra == 'sms'
+Description-Content-Type: text/markdown
+
+# Finlet
+
+**An evaluation harness for AI trading agents.** Daily-timeframe. US equities. Long-only.
+
+Test your AI agent's *reasoning* — not just its algorithms.
+
+Finlet is an agent evaluation harness that tests whether AI trading agents make sound decisions with the information available to them. It provides a simulation clock that controls what data your agent can see, a Date Ceiling Enforcer that strips future data from every response, and a tamper-evident reasoning trace that logs every query and decision with SHA-256 checksums.
+
+This is not a backtester. Backtesters test strategies against historical data. Finlet tests whether your agent *reasons well* given the same information a human analyst would have had on that date.
+
+## Why Finlet?
+
+Most backtesting frameworks test *algorithms*. Finlet tests *reasoning*.
+
+As a backtester, Finlet would lose to QuantConnect on every metric — data coverage, asset classes, speed. As an evaluation harness, it has no direct product competitor.
+
+- **Date Ceiling Enforcer** — Defense-in-depth runtime enforcement strips any data past the simulation clock. Property-based tests prove no future item passes. No competitor has an equivalent.
+- **SHA-256 Reasoning Trace** — Every query, decision, and order is logged with tamper-evident checksums. No backtester tracks agent reasoning.
+- **Cross-Scenario Leaderboard** — Standardized evaluation with composite scoring across returns, risk, drawdown, reasoning quality, and information efficiency
+- **Real data sources** — S3 Parquet price data, SEC EDGAR filings, FRED economic indicators, Finnhub news — not synthetic datasets
+- **MCP native** — Connect Claude Code (or any MCP client) directly as a trading agent via 16 purpose-built tools
+
+## v1 Scope
+
+Finlet v1 is intentionally scoped to daily-timeframe, US-equities, long-only evaluation. These are design choices, not gaps:
+
+| Scope Decision | Rationale |
+|---|---|
+| **EOD data only** | Agent evaluation tests reasoning quality, not execution speed |
+| **US equities only** | Deepest data coverage (price, filings, economic, news) |
+| **Long-only** | Isolates reasoning from margin/borrow mechanics |
+| **No partial fills** | Honest about what EOD data supports (no order book depth) |
+| **No live/paper trading** | Evaluation harness, not trading platform |
+
+See [docs/V1_SCOPE.md](docs/V1_SCOPE.md) for the complete scope document with rationale.
+
+---
+
+## Quick Start
+
+> **For AI Agents:** Visit [finlet.dev/setup](https://finlet.dev/setup) for a structured setup guide with copy-paste configs for REST API, MCP, and CLI. Machine-readable agent index available at [finlet.dev/llms.txt](https://finlet.dev/llms.txt).
+
+### Cloud (finlet.dev)
+
+```bash
+# 1. Sign up at finlet.dev and get your API key
+
+# 2. Create a session
+curl -X POST https://finlet.dev/sessions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "tech-test",
+    "start_time": "2024-01-02T09:30:00Z",
+    "initial_capital": 100000,
+    "universe": ["AAPL", "GOOGL", "MSFT", "NVDA"]
+  }'
+
+# 3. Open the dashboard
+open https://finlet.dev
+```
+
+### Local
+
+```bash
+# Install
+pip install finlet
+
+# Start the server
+finlet serve
+
+# Create a session
+curl -X POST http://localhost:8000/sessions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "tech-test",
+    "start_time": "2024-01-02T09:30:00Z",
+    "initial_capital": 100000,
+    "universe": ["AAPL", "GOOGL", "MSFT", "NVDA"]
+  }'
+
+# Open the dashboard
+open http://localhost:8000
+```
+
+### Connect Claude Code as a Trading Agent
+
+Add to your Claude Code MCP config (`.claude.json` or VS Code settings):
+
+```json
+{
+  "mcpServers": {
+    "finlet": {
+      "command": "finlet",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then tell Claude: *"Use Finlet to analyze AAPL's fundamentals as of January 2024 and decide whether to buy."*
+
+### Connect via REST API
+
+Any HTTP client works. Point your agent at the REST API:
+
+```python
+import httpx
+
+async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+    # Get current simulation time
+    clock = await client.get(f"/sessions/{session_id}/clock")
+
+    # Query price data (automatically filtered to sim time)
+    prices = await client.get(f"/sessions/{session_id}/market/price",
+                              params={"ticker": "AAPL", "period": "3mo"})
+
+    # Submit a trade with reasoning
+    await client.post(f"/sessions/{session_id}/trade/order", json={
+        "side": "BUY",
+        "ticker": "AAPL",
+        "quantity": 50,
+        "order_type": "MARKET",
+        "reasoning": "Strong Q4 earnings beat, raising guidance, reasonable P/E"
+    })
+```
+
+---
+
+## Features
+
+### Simulation Clock
+
+Three modes to control how time flows:
+
+| Mode | Behavior |
+|------|----------|
+| **FROZEN** | Clock is stopped. Agent can make unlimited queries at the current time. |
+| **STEPPING** | Clock advances by a fixed interval when explicitly told to step. |
+| **CONTINUOUS** | Clock advances in real-time at a configurable speed multiplier. |
+
+The clock only moves forward when explicitly advanced. No implicit time progression.
+
+### Date Ceiling Enforcer
+
+Defense-in-depth protection against future data leakage:
+
+- All timestamps in response data must be <= current sim clock time
+- Items with timestamps after the ceiling are **stripped**
+- Items without timestamps are **excluded by default**
+- Strip counts are logged internally but **never exposed to the agent** (that would leak information about future data existence)
+
+### Portfolio Engine
+
+Full portfolio tracking with computed metrics:
+
+- Cash tracking, position management, P&L (realized + unrealized)
+- Sharpe ratio, max drawdown, win rate
+- Equity curve time series for charting
+
+### Order System
+
+Market, limit, and stop orders with full lifecycle tracking:
+
+```
+PENDING -> FILLED | CANCELLED | REJECTED
+```
+
+Each order supports an optional `reasoning` field for trace logging.
+
+### Plugin System
+
+Extensible data source architecture. Built-in plugins connect to real financial APIs:
+
+| Plugin | Data Type | API Key | Notes |
+|--------|-----------|---------|-------|
+| **PricePlugin** | Price (OHLCV) | None | S3 Parquet-backed historical price data. |
+| **EDGAR** | SEC Filings | None* | 10-K, 10-Q, 8-K, 13-F, Form 4. *Requires User-Agent email. |
+| **FRED** | Economic | Free key | GDP, unemployment, CPI, rates. ALFRED vintage dates. |
+| **Finnhub** | News + Fundamentals | User key | Company news, earnings, fundamentals. 60 calls/min free tier. |
+
+```bash
+# Configure plugin API keys
+finlet plugins add finnhub --api-key=YOUR_KEY
+finlet plugins add fred --api-key=YOUR_KEY
+```
+
+Plugin configuration is stored at `~/.finlet/plugins.json` (never committed to git).
+
+### Reasoning Trace
+
+Every agent interaction is logged:
+
+- **Action type**: What kind of query or action (price, news, filing, order, etc.)
+- **Sim time + real time**: When it happened in simulation and wall clock
+- **Request params**: What was requested
+- **Response summary**: What was returned
+- **Reasoning**: Agent's own explanation for the action
+- **Latency**: How long the operation took
+
+### Leaderboard
+
+Standardized evaluation across 5 scenarios with composite scoring. Agents are scored on:
+
+- Portfolio returns vs. benchmark
+- Risk-adjusted returns (Sharpe ratio)
+- Maximum drawdown
+- Reasoning quality
+- Information efficiency (returns per API call)
+
+Opt in to data sharing to appear on the public leaderboard and compare your agent against others.
+
+---
+
+## Architecture
+
+```
++-------------------------------------------------------------+
+|                     AI Trading Agent                         |
+|               (Claude Code, custom bot, etc.)                |
++----------+------------------------------+--------------------+
+           | MCP (stdio)                  | REST API
+           v                              v
++-------------------------------------------------------------+
+|                        Finlet Server                         |
+|  +-----------+  +-----------+  +----------------------+     |
+|  |  MCP      |  |  FastAPI   |  |   Static Dashboard   |     |
+|  |  Server   |  |  Routes    |  |   (HTML/JS/CSS)      |     |
+|  +-----+-----+  +-----+-----+  +----------------------+     |
+|        +-------+-------+                                     |
+|                v                                             |
+|  +------------------------------------------------------+   |
+|  |                   Session Engine                       |   |
+|  |  +---------+  +-----------+  +------------------+     |   |
+|  |  |  Clock   |  | Portfolio  |  |  Order Executor  |     |   |
+|  |  | (frozen) |  |  Engine    |  |                  |     |   |
+|  |  +---------+  +-----------+  +------------------+     |   |
+|  +------------------------+-------------------------------+   |
+|                           v                                   |
+|  +------------------------------------------------------+   |
+|  |              Date Ceiling Enforcer                     |   |
+|  |         (strips data after sim clock time)             |   |
+|  +------------------------+-------------------------------+   |
+|                           v                                   |
+|  +------------------------------------------------------+   |
+|  |                 Plugin Registry                        |   |
+|  |  +----------+ +-------+ +------+ +---------------+    |   |
+|  |  |  Price   | | EDGAR | | FRED | |    Finnhub    |    |   |
+|  |  |(S3 Parqt)| |(filing| |(econ)| |(news+fundmntl)|    |   |
+|  |  +----------+ +-------+ +------+ +---------------+    |   |
+|  +------------------------------------------------------+   |
+|                           |                                   |
+|  +------------------------v-------------------------------+   |
+|  |            SQLite (per-session DB)                      |   |
+|  |     ~/.finlet/sessions/{id}/session.db                  |   |
+|  +------------------------------------------------------+   |
++-------------------------------------------------------------+
+```
+
+---
+
+## API Reference
+
+Base URL: `http://localhost:8000` (local) or `https://finlet.dev` (cloud)
+
+### Sessions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/sessions` | Create a new session |
+| `GET` | `/sessions` | List all sessions |
+| `GET` | `/sessions/{id}` | Get session state |
+| `DELETE` | `/sessions/{id}` | End a session |
+| `POST` | `/sessions/{id}/configure` | Update session config |
+
+### Clock
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/sessions/{id}/clock` | Current clock state |
+| `POST` | `/sessions/{id}/clock/freeze` | Freeze the clock |
+| `POST` | `/sessions/{id}/clock/step` | Step by interval |
+| `POST` | `/sessions/{id}/clock/step-to` | Step to a specific time |
+| `POST` | `/sessions/{id}/clock/play` | Start continuous mode |
+| `POST` | `/sessions/{id}/clock/stop` | Stop continuous mode |
+
+### Market Data
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/sessions/{id}/market/price` | Price data (OHLCV) |
+| `POST` | `/sessions/{id}/market/search-news` | Search news articles |
+| `GET` | `/sessions/{id}/market/fundamentals` | Company fundamentals |
+| `GET` | `/sessions/{id}/market/filings` | SEC filings |
+| `GET` | `/sessions/{id}/market/economic` | Economic indicators |
+
+### Trading
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/sessions/{id}/trade/order` | Submit an order |
+| `GET` | `/sessions/{id}/trade/orders` | List orders |
+| `GET` | `/sessions/{id}/trade/orders/{oid}` | Order detail |
+| `DELETE` | `/sessions/{id}/trade/orders/{oid}` | Cancel an order |
+
+### Portfolio
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/sessions/{id}/portfolio` | Portfolio state + metrics |
+| `GET` | `/sessions/{id}/portfolio/history` | Equity curve time series |
+| `GET` | `/sessions/{id}/trace` | Reasoning trace log |
+
+Full interactive docs at `/docs` when the server is running.
+
+---
+
+## MCP Tools
+
+When connected via MCP, these tools are available to your AI agent:
+
+| Tool | Description |
+|------|-------------|
+| `get_price_data` | Fetch OHLCV price data for a ticker |
+| `search_news` | Search news articles by keyword/ticker |
+| `get_fundamentals` | Get company financial fundamentals |
+| `get_filings` | Retrieve SEC filings |
+| `get_economic_data` | Get economic indicators (GDP, CPI, etc.) |
+| `submit_order` | Place a buy/sell order |
+| `get_portfolio` | View current portfolio state |
+| `get_sim_time` | Check current simulation time |
+| `advance_time` | Step the simulation clock forward |
+| `freeze_time` | Freeze the simulation clock |
+
+---
+
+## CLI Reference
+
+```bash
+finlet serve                    # Start API server + dashboard
+finlet session create           # Create a new session
+  --name TEXT                   #   Session name
+  --start TEXT                  #   Start datetime (ISO format)
+  --capital FLOAT               #   Initial capital (default: 100000)
+  --universe TEXT               #   Comma-separated ticker list
+finlet session list             # List all sessions
+finlet plugins list             # Show plugin status
+finlet plugins add NAME         # Configure a plugin
+  --api-key TEXT                #   API key for the plugin
+finlet mcp                      # Start MCP server (stdio)
+```
+
+---
+
+## Tech Stack
+
+- **Python 3.12+** — Async throughout, type hints everywhere
+- **FastAPI** — REST API with automatic OpenAPI docs
+- **MCP SDK** — Model Context Protocol server for LLM integration
+- **SQLite** — Per-session database via aiosqlite + SQLModel
+- **TradingView Lightweight Charts** — Dashboard charting (MIT, via CDN)
+
+## Contributing
+
+1. Clone the repo
+2. Install in dev mode: `pip install -e ".[dev]"`
+3. Run tests: `pytest`
+4. Follow the code conventions in `CLAUDE.md`
+
+Key rules:
+- All datetimes in UTC internally
+- Async functions everywhere — no sync I/O in the hot path
+- Error messages must be specific and actionable
+- Every plugin response goes through the date ceiling enforcer
+- Mock external APIs in tests — no real network calls
+
+## Disclaimers
+
+Finlet is provided for educational and research purposes only. It is not financial advice and should not be used as the basis for any investment decisions.
+
+Past performance of simulated trading strategies does not guarantee future results. All market data is historical and provided by third-party sources subject to their respective terms of service.
+
+Finlet is not affiliated with any stock exchange, broker, or financial institution.
+
+## License
+
+Proprietary

finlet-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+finlet/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+finlet/cli.py,sha256=mJM0dJps3Hq0C2QKgivNQFG5_BrtZ6bNpK3sxFbMhsE,7981
+finlet/config.py,sha256=yHQg_h5GRXJgjsuFX3JzSyV0WSv0OONvLSizZVpdxtI,6548
+finlet-0.0.1.dist-info/METADATA,sha256=LFrXy6f_VnFyinEcwB0oc8xCIeK4lAEIrokLkaqCUO8,17583
+finlet-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+finlet-0.0.1.dist-info/entry_points.txt,sha256=N9XOBMjS1Zw0Q7Fmev4VZNpi-uHulse99woMbsuYBLg,42
+finlet-0.0.1.dist-info/licenses/LICENSE,sha256=Qy1lchoN5yOAoHcIF4ZS9N3suMh-ZTko5IaXndl5d4g,882
+finlet-0.0.1.dist-info/RECORD,,

finlet-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

finlet-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+finlet = finlet.cli:app

finlet-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Finlet Contributors. All rights reserved.
+
+This software and associated documentation files (the "Software") are
+proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of the Software, in whole or in part, via any medium,
+is strictly prohibited without the prior written permission of the copyright
+holder.
+
+The Software is provided "AS IS", without warranty of any kind, express or
+implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose, and noninfringement. In no event shall the
+authors or copyright holders be liable for any claim, damages, or other
+liability, whether in an action of contract, tort, or otherwise, arising
+from, out of, or in connection with the Software or the use or other
+dealings in the Software.
+
+For licensing inquiries, contact: [insert contact email]