finlet 0.0.1__tar.gz

finlet-0.0.1/.claude/rules/api-routes.md

@@ -0,0 +1,41 @@
+---
+paths:
+  - "finlet/api/**"
+---
+
+# API Route Rules
+
+## FastAPI Patterns
+- Each route file: `router = APIRouter(tags=[...])` — registered in app.py
+- Request/response models as Pydantic `BaseModel` in the same route file
+- Use `HTTPException` for errors with specific detail messages
+- Thin route handlers — delegate business logic to core/domain modules
+
+## Authentication
+- All endpoints require `X-API-Key` via Bearer scheme (`require_api_key` dependency)
+- `UserRecord`: id, email, tier, MFA status — injected via `Depends`
+- Session ownership enforced via `get_user_session(session_id, user)` in deps.py
+- Returns 404 for both missing AND unauthorized sessions (no info leakage)
+- Registration rate-limited: 5/hour/IP
+
+## Middleware Stack (ordered)
+- `CorrelationIDMiddleware`: X-Request-ID binding to structlog context
+- `SecurityHeadersMiddleware`: X-Frame-Options, CSP, HSTS, etc.
+- `RequestSizeLimitMiddleware`: 413 for bodies > 1MB
+- `CORSMiddleware`: configurable origins
+- Marketplace: `GeoBlockMiddleware`, `DisclaimerInjectionMiddleware`
+
+## State Management
+- `state.py`: `get_sessions()`, `get_registry()`, `get_sessions_lock()`
+- Sessions dict and plugin registry are module-level singletons
+- App lifespan: init_engines -> load_all_keys -> load_all_sessions -> run_migrations
+
+## Error Codes
+- 404: missing/unauthorized sessions or orders
+- 422: validation errors
+- 429: rate limits (pass through plugin details with reset timing)
+- 503: plugin unavailability
+
+## General
+- Use `structlog.get_logger()` for logging
+- Async route handlers — no sync I/O

finlet-0.0.1/.claude/rules/core-engine.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "finlet/core/**"
+---
+
+# Core Engine Rules
+
+## Simulation Clock (clock.py)
+- Three modes: FROZEN, STEPPING, CONTINUOUS — clock ONLY moves forward on explicit advance
+- `freeze()`, `step(interval)`, `step_to(datetime)`, `play(speed)`, `get_time()`
+- Market hours awareness: skip weekends/after-hours when configured
+- All times stored in UTC — convert only for display
+
+## Date Ceiling Enforcer (enforcer.py)
+- Every plugin response passes through `DateCeilingEnforcer` — no exceptions
+- Items with timestamps > ceiling are stripped; items without timestamps excluded by default
+- Log stripped count internally but NEVER expose to the agent (leaks future data existence)
+- `PluginResponse` model lives here, not in plugins
+
+## Order System (orders.py)
+- Types: MARKET, LIMIT, STOP with BUY/SELL sides
+- Status flow: PENDING -> FILLED | CANCELLED | REJECTED
+- `OrderBook` uses `asyncio.Lock()` to serialize submissions and fills
+- v1: no slippage, no partial fills, no short selling, no commission
+
+## Portfolio (portfolio.py)
+- Tracks cash, positions (with avg_entry_price), realized/unrealized P&L
+- Computed metrics: total_value, sharpe_ratio, max_drawdown, win_rate
+- Equity curve: time series of `EquitySnapshot` for charting
+- All mutations protected by `asyncio.Lock()` for concurrency safety
+- Uses Pydantic `computed_field` for derived values
+
+## Session (session.py)
+- Lifecycle: CREATED -> ACTIVE -> PAUSED -> ACTIVE -> COMPLETED
+- Each session owns: clock, portfolio, order book, trace log, user_id
+- `SessionConfig`: start_time, end_time, initial_capital, universe, time_step
+
+## General
+- Async functions only — no sync I/O
+- Use `structlog.get_logger()` for logging
+- Pydantic models for all data structures
+- One file per module

finlet-0.0.1/.claude/rules/dashboard.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - "dashboard/**"
+---
+
+# Dashboard Rules
+
+## Technology
+- Vanilla HTML + JavaScript + CSS — no build step, no framework
+- Served as static files by FastAPI
+- TradingView Lightweight Charts (free, MIT) via CDN for price/equity curves
+
+## Pages
+- `index.html`: Main dashboard — session selector, overview, charts, tables
+- `auth.html` + `auth.js` + `auth.css`: Authentication flow
+- `leaderboard.html` + `leaderboard.js`: Leaderboard display
+- `settings.html` + `settings.js` + `settings.css`: User settings
+- `billing.html` + `billing.js` + `billing.css`: Billing/subscription
+
+## Design
+- Dark theme by default, CSS variables for theming
+- Desktop-primary layout
+- Polls session state every 2 seconds
+
+## Dashboard Views
+- Session selector: dropdown/sidebar listing sessions
+- Overview panel: sim time, portfolio value, cash, P&L, clock controls
+- Equity curve: portfolio value over sim time with buy-and-hold benchmark
+- Positions table: open positions with color-coded P&L
+- Order log: scrollable table with expandable reasoning
+- Reasoning trace: timeline/feed of agent actions
+- Plugin health: status cards per plugin
+
+## API Integration
+- All data fetched from FastAPI REST endpoints
+- Bearer token auth via stored API key
+- Error states shown to user with actionable messages

finlet-0.0.1/.claude/rules/database.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "finlet/db/**"
+---
+
+# Database Rules
+
+## SQLModel + aiosqlite
+- Models extend `SQLModel` with `table=True`
+- Async engines via `create_async_engine` with `aiosqlite` driver
+- WAL mode enabled on all connections via SQLAlchemy event listeners
+- Engines created once at startup (`init_engines()`), cached, disposed on shutdown
+
+## Database Layout
+- Per-session: `~/.finlet/sessions/{session_id}/session.db`
+- Global auth: `~/.finlet/auth.db` (users, API keys)
+- Global leaderboard: in `~/.finlet/finlet.db`
+- Marketplace: `~/.finlet/marketplace.db`
+
+## Models (models.py)
+- `SessionModel`, `OrderModel`, `PositionModel`, `PortfolioSnapshotModel`, `TraceEntryModel`
+- `ApiKeyModel` for auth persistence
+- `_utcnow()` helper for consistent UTC timestamps
+- `_new_id()` via `uuid.uuid4()` for primary keys
+
+## Persistence (persistence.py)
+- Save after each mutation — no batching or background flushing
+- `save_session()`, `load_all_sessions()`, `delete_session_db()`
+- Uses `structlog.get_logger()` for logging
+
+## Migrations (migrations/)
+- Alembic-based, programmatic runner (no subprocess calls)
+- `render_as_batch=True` always for SQLite compatibility
+- Existing DBs without alembic_version are stamped at baseline
+- `run_migrations()` called at app startup
+- `migrate_session_db()` for lazy per-session migration
+
+## General
+- Async only — no sync database operations
+- `asyncio.Lock` guards engine creation to prevent races

finlet-0.0.1/.claude/rules/deploy-ops.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "deploy/**"
+  - ".github/**"
+---
+
+# Deploy & Ops Rules
+
+## Infrastructure
+- Systemd services: `finlet.service` (API), `finlet-mcp.service` (MCP)
+- Caddy reverse proxy (Caddyfile)
+- fail2ban integration for brute-force protection
+- logrotate config for log management
+- SQLite backup script (`backup-sqlite.sh`)
+
+## Deployment Scripts
+- `deploy.sh`: production deployment
+- `rollback.sh`: rollback to previous version
+- `RUNBOOK.md`: operational procedures
+- `aws/user-data.sh`: cloud-init bootstrap (one-time server setup)
+
+## CI/CD Pipeline (.github/workflows/)
+- Pipeline order: ruff lint -> mypy type check -> pip-audit -> pytest -> deploy
+- All checks must pass before deploy
+
+## AWS
+- AWS deployment configs in `deploy/aws/`
+
+## Conventions
+- Shell scripts must be POSIX-compatible where possible
+- Always test rollback procedures when changing deploy scripts
+- Security: no secrets in config files — use environment variables

finlet-0.0.1/.claude/rules/file-ownership.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**"
+---
+
+## File Ownership (Agent Teams)
+- `finlet/core/` + `tests/core/` → engine
+- `finlet/plugins/` + `tests/plugins/` → plugins
+- `finlet/api/`, `finlet/mcp/`, `finlet/cli.py` + `tests/api/`, `tests/mcp/`, `tests/test_cli.py` → api
+- `finlet/auth/` + `tests/auth/` → api (auth is L2, owned by api team)
+- `finlet/billing/` + `tests/billing/` → api (billing is L2, owned by api team)
+- `finlet/leaderboard/` + `tests/leaderboard/` → leaderboard
+- `finlet/marketplace/` + `tests/marketplace/` → marketplace
+- `dashboard/` → dashboard
+- `finlet/db/`, `finlet/utils/`, `pyproject.toml`, `README.md` → infra
+- `deploy/`, `.github/` → ops
+- `docs/` → docs

finlet-0.0.1/.claude/rules/leaderboard.md

@@ -0,0 +1,36 @@
+---
+paths:
+  - "finlet/leaderboard/**"
+---
+
+# Leaderboard Rules
+
+## Scoring (scoring.py)
+- Composite score: 0.30*sharpe + 0.25*return + 0.25*(1-drawdown) + 0.20*consistency
+- Consistency = 1 - (std_dev / mean) of per-scenario returns
+- All values min-max normalized to [0,1] relative to all entries
+
+## Benchmark Scenarios (benchmarks.py)
+- Frozen dataclass `BenchmarkScenario`: id, name, time period, universe, capital
+- 5 standard scenarios with default universe (AAPL, MSFT, etc.)
+- Scenarios are immutable — never modify existing benchmarks
+
+## Runner (runner.py)
+- Executes all scenarios for a leaderboard submission
+- Self-play mode: deterministic pseudo-prices (seeded random walk)
+- Reproducible without real market data APIs
+- Uses core Session, OrderBook, Portfolio directly
+
+## Profiles (profiles.py)
+- `AgentProfile` with `ScenarioScore` per benchmark
+- Persisted to SQLite via leaderboard_persistence.py
+
+## API Strategy (api_strategy.py)
+- Drives agent strategies against the benchmark runner
+
+## Rate Limits
+- Benchmark submissions limited to 10/day/user to prevent abuse
+
+## General
+- Async functions where applicable
+- Uses stdlib `logging` in runner (not structlog — legacy)

finlet-0.0.1/.claude/rules/marketplace.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "finlet/marketplace/**"
+---
+
+# Marketplace Rules
+
+## Compliance-First Architecture
+- All marketplace code must reference LEGAL_REQUISITES.md for requirements
+- FTC, SEC, and state-level regulations govern marketplace behavior
+- When in doubt, block/restrict rather than allow
+
+## Geo-blocking (geo_middleware.py, geo_config.py, geo_ip.py)
+- OFAC-sanctioned countries blocked — returns HTTP 451
+- UK blocked (FCA risk)
+- X-Forwarded-For trust: configure via FINLET_TRUSTED_PROXY_COUNT
+- Exempt paths: health, docs, legal endpoints bypass geo-blocking
+
+## Financial Disclaimers (disclaimer_middleware.py, disclaimers.py)
+- Auto-injected into all /marketplace/* responses via middleware
+- Platform-controlled — developers cannot remove or modify
+- Context-aware: different disclaimers for listings, purchases, search, leaderboard
+
+## Reviews (review_compliance.py)
+- FTC Consumer Review Rule compliance (effective Oct 2024)
+- Verified purchase required, no sentiment filtering, no self-reviews
+- Sort by recency, not rating — admin can only hide for ToS violations
+
+## Tax (tax.py, tax_forms.py)
+- Stripe Tax API for sales tax calculation
+- Tax shown before payment (FTC pre-purchase transparency)
+- All Stripe calls async via httpx
+
+## Models & Persistence
+- SQLModel tables in `~/.finlet/marketplace.db`
+- DeveloperProfile, OnboardingSteps, StrategyListing, etc.
+- Stripe Connect for developer payouts
+
+## Prohibited Claims (prohibited_claims.py)
+- Automated scanning for SEC-violating claims in strategy descriptions
+- Block guaranteed return claims, misleading performance statements
+
+## General
+- Use `structlog.get_logger()` for logging
+- Async functions only
+- Use Pydantic models for request/response validation

finlet-0.0.1/.claude/rules/mcp-server.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "finlet/mcp/**"
+---
+
+# MCP Server Rules
+
+## FastMCP Patterns
+- Single `server.py` using `FastMCP` from `mcp.server.fastmcp`
+- Server name: "finlet" with descriptive instructions string
+- Tools registered as decorated async functions
+
+## Tool Registration
+- Each tool has a clear description helping LLMs understand when to use it
+- Include example parameter values in descriptions
+- Tools: get_price_data, search_news, get_fundamentals, get_filings, get_economic_data
+- Trading: submit_order, get_portfolio
+- Clock: get_sim_time, advance_time, freeze_time
+
+## Shared Logic
+- Reuse state from `finlet.api.state` (get_sessions, get_registry)
+- Reuse `DateCeilingEnforcer` from core — every data response is enforced
+- Interval map: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w -> seconds
+- `_get_session()` helper validates session exists
+
+## Error Handling
+- Return specific, actionable error messages (same standard as API/plugins)
+- Plugin errors surfaced with rate limit details when applicable
+
+## General
+- Async functions only
+- Use structlog for logging
+- CLI entry point: `finlet mcp` starts server over stdio

finlet-0.0.1/.claude/rules/plugins.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "finlet/plugins/**"
+---
+
+# Plugin Rules
+
+## DataPlugin Interface (base.py)
+- All plugins extend `DataPlugin` ABC with: `initialize()`, `query()`, `health_check()`
+- `plugin_type`: price | news | fundamentals | filings | economic
+- `PluginRegistry` manages loading and routing queries by type
+- `CircuitBreaker` per plugin prevents cascading failures (threshold=5, reset=60s)
+
+## PluginResponse Format
+- Return `PluginResponse` from `finlet.core.enforcer` — NOT a custom format
+- Include: items, source, query_params, ceiling_applied, items_pre_filter, items_post_filter
+- Include rate_limit_remaining and rate_limit_reset when applicable
+
+## Date Ceiling Enforcer
+- Every query receives `ceiling_time` — filter data to this boundary
+- This is defense-in-depth: plugins filter AND the core enforcer re-filters
+
+## Error Messages — MUST be specific and actionable
+- Good: "Finnhub rate limit exceeded: 0/60 calls remaining, resets in 42 seconds"
+- Bad: "API error"
+- Good: "PricePlugin: No data available for ticker 'INVALID'. Check ticker symbol against supported universe"
+- Bad: "Data not found"
+
+## Built-in Plugins
+- **price_plugin** (S3 Parquet via pyarrow + boto3): OHLCV from Databento DBEQ.BASIC + Quandl WIKI data lake
+- **edgar_plugin** (edgartools): SEC filings. Filter by `filedAt <= ceiling`
+- **fred_plugin** (fredapi): Economic data. Use ALFRED vintage dates for point-in-time accuracy
+- **finnhub_plugin** (finnhub-python): News + fundamentals. 60 calls/min free tier
+- **econ_plugin**: Economic indicators aggregation
+
+## General
+- Use `structlog.get_logger()` — not stdlib logging
+- Use `httpx` for async HTTP calls
+- Async functions only — no sync I/O

finlet-0.0.1/.claude/rules/testing.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "tests/**"
+---
+
+# Testing Rules
+
+## Framework
+- pytest + pytest-asyncio
+- Root conftest at `tests/conftest.py` — shared fixtures (opt-in, no autouse)
+- Local conftest fixtures override root fixtures per pytest scoping rules
+
+## Fixtures (from root conftest)
+- `test_app`: TestClient with mocked lifespan (patches slow startup ops)
+- `api_key` / `auth_headers`: creates API key + Bearer header for a test user
+- `isolated_sessions`: clean session dict per test
+- `mock_registry`: PluginRegistry with no real plugins
+- `_run_async()`: helper to run async coroutines from sync test code
+
+## Mocking
+- Mock ALL external APIs — no real network calls in tests
+- Mock plugin responses, not the enforcer (enforcer is part of the contract)
+- Use `unittest.mock.patch` or `pytest-mock` for patching
+
+## Edge Cases to Test
+- Market hours boundaries (weekends, after-hours transitions)
+- Order fills at price gaps
+- Date ceiling enforcer stripping future data
+- Portfolio metrics with no trades (division by zero guards)
+- Session ownership checks (user A cannot access user B's session)
+- Rate limit boundaries
+
+## Conventions
+- Test files mirror source structure: `tests/core/`, `tests/plugins/`, etc.
+- One test file per source module
+- Descriptive test names: `test_enforcer_strips_future_items`
+- Use `pytest.raises` for expected exceptions
+
+## CI Pipeline
+- ruff lint -> mypy type check -> pip-audit -> pytest -> deploy

finlet-0.0.1/.claude/skills/add-order-type/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: add-order-type
+description: Scaffold a new order type in Finlet's trading engine. Use when the user wants to add a new order type like TRAILING_STOP, OCO, or BRACKET to the order system.
+disable-model-invocation: true
+argument-hint: <order-type-name>
+---
+
+# Add a New Order Type
+
+Add a new order type `$ARGUMENTS` to Finlet's trading engine.
+
+## Steps
+
+### 1. Add to OrderType enum
+
+In `finlet/core/orders.py`, add the new type to the `OrderType` enum.
+
+### 2. Implement fill logic
+
+In the OrderBook class, add fill logic for the new order type:
+- When does it trigger?
+- What price does it fill at?
+- What are the edge cases?
+
+### 3. Add API route support
+
+Update `finlet/api/routes_trade.py` to accept the new order type in request validation.
+
+### 4. Add MCP tool support
+
+Update `finlet/mcp/server.py` to document the new order type in the `submit_order` tool description.
+
+### 5. Write tests
+
+In `tests/core/test_orders.py`:
+- Test order creation with new type
+- Test fill conditions
+- Test cancellation
+- Test edge cases (price gaps, market hours boundaries)
+
+### 6. Update documentation
+
+If the new order type has non-obvious behavior, add a note to `docs/ARCHITECTURE.md` under the Order System section.
+
+### 7. Verify
+
+```bash
+pytest tests/core/test_orders.py tests/api/test_routes_trade.py -v
+```
+
+## Reference
+
+- `finlet/core/orders.py` — OrderType enum, Order model, OrderBook
+- `docs/ARCHITECTURE.md` — Order system specification

finlet-0.0.1/.claude/skills/api-conventions/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: api-conventions
+description: Finlet API development conventions and patterns. Applies when writing or modifying FastAPI routes, MCP tools, or CLI commands — covers authentication, session ownership, error responses, and route organization.
+user-invocable: false
+---
+
+# API Development Conventions
+
+These conventions apply when working on `finlet/api/`, `finlet/mcp/`, and `finlet/cli.py`.
+
+## Authentication
+- All endpoints require a valid `Authorization: Bearer <key>` header (FastAPI `HTTPBearer` scheme)
+- Use the `require_api_key` dependency for protected endpoints; it validates the Bearer token and returns a `UserRecord`
+- Use `optional_api_key` for public endpoints that gain features with auth
+- API keys are 32-char hex tokens, SHA-256 hashed before storage, persisted to SQLite with in-memory cache
+- Registration is rate-limited to 5 per hour per IP
+- Session ownership is enforced — keys can only access their own sessions
+
+## Route Organization
+- One route file per resource domain: `routes_session.py`, `routes_clock.py`, etc.
+- Each route file defines a FastAPI `APIRouter`
+- Routers are registered in `finlet/api/app.py`
+
+## Error Responses
+- `422` — Validation errors (Pydantic)
+- `404` — Missing sessions/orders
+- `429` — Rate limits (pass through from plugins with reset timing)
+- `503` — Plugin unavailability
+
+## Session Ownership
+- Every endpoint that accesses a session must verify ownership
+- Use the dependency injection pattern from `finlet/api/deps.py`
+- Never allow cross-user session access
+
+## MCP Server
+- Tools mirror REST API functionality
+- Each tool has a clear description to help LLMs understand when to use it
+- Include example parameter values in descriptions
+- Tool names: `get_price_data`, `search_news`, `get_fundamentals`, `get_filings`, `get_economic_data`, `submit_order`, `get_portfolio`, `get_sim_time`, `advance_time`, `freeze_time`
+
+## CLI (typer)
+- `finlet serve` — Start API server + serve dashboard
+- `finlet session create/list` — Session management
+- `finlet plugins list/add` — Plugin management
+- `finlet mcp` — Start MCP server over stdio
+
+## Middleware
+- Security middleware in `finlet/api/security_middleware.py`
+- Rate limiting in `finlet/api/rate_limit.py`
+- All middleware is async