Delete API_USAGE.md

API_USAGE.md

@@ -1,500 +0,0 @@
-# API Usage Guide
-
-Complete guide for using the SEC Financial Report MCP Server API.
-
-## Base URL
-
-After deployment: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
-
-## Interactive Documentation
-
-- **Swagger UI**: `{BASE_URL}/docs`
-- **ReDoc**: `{BASE_URL}/redoc`
-
-## Quick Start
-
-### Python Example
-
-```python
-import requests
-
-BASE_URL = "https://YOUR_SPACE_URL.hf.space"
-
-# 1. Search company
-response = requests.post(
-    f"{BASE_URL}/api/search_company",
-    json={"company_name": "NVIDIA"}
-)
-company = response.json()
-print(f"Found: {company['name']} (CIK: {company['cik']})")
-
-# 2. Get financial data
-response = requests.post(
-    f"{BASE_URL}/api/get_financial_data",
-    json={"cik": company['cik'], "period": "2024"}
-)
-data = response.json()
-print(f"Revenue: ${data['total_revenue']:,.0f}")
-print(f"Net Income: ${data['net_income']:,.0f}")
-print(f"EPS: ${data['earnings_per_share']:.2f}")
-```
-
-## Base URL
-
-```
-https://your-space-name.hf.space
-```
-
-## API Endpoints
-
-### 1. Search Company by Name
-
-**Endpoint:** `POST /api/search_company`
-
-**Request:**
-```json
-{
-  "company_name": "NVIDIA"
-}
-```
-
-**Response:**
-```json
-{
-  "cik": "0001045810",
-  "name": "NVIDIA CORP",
-  "ticker": "NVDA",
-  "error": null
-}
-```
-
-**cURL Example:**
-```bash
-curl -X POST "https://your-space-name.hf.space/api/search_company" \
-  -H "Content-Type: application/json" \
-  -d '{"company_name": "NVIDIA"}'
-```
-
-**Python Example:**
-```python
-import requests
-
-url = "https://your-space-name.hf.space/api/search_company"
-payload = {"company_name": "NVIDIA"}
-response = requests.post(url, json=payload)
-print(response.json())
-```
-
----
-
-### 2. Get Company Information
-
-**Endpoint:** `POST /api/get_company_info`
-
-**Request:**
-```json
-{
-  "cik": "0001045810"
-}
-```
-
-**Response:**
-```json
-{
-  "cik": "0001045810",
-  "name": "NVIDIA CORP",
-  "tickers": ["NVDA"],
-  "sic": "3674",
-  "sic_description": "Semiconductors & Related Devices",
-  "error": null
-}
-```
-
-**cURL Example:**
-```bash
-curl -X POST "https://your-space-name.hf.space/api/get_company_info" \
-  -H "Content-Type: application/json" \
-  -d '{"cik": "0001045810"}'
-```
-
-**Python Example:**
-```python
-import requests
-
-url = "https://your-space-name.hf.space/api/get_company_info"
-payload = {"cik": "0001045810"}
-response = requests.post(url, json=payload)
-print(response.json())
-```
-
----
-
-### 3. Get Company Filings
-
-**Endpoint:** `POST /api/get_company_filings`
-
-**Request (All form types):**
-```json
-{
-  "cik": "0001045810",
-  "form_types": null
-}
-```
-
-**Request (Specific form types):**
-```json
-{
-  "cik": "0001045810",
-  "form_types": ["10-K", "10-Q"]
-}
-```
-
-**Response:**
-```json
-{
-  "filings": [
-    {
-      "form_type": "10-K",
-      "filing_date": "2024-02-21",
-      "accession_number": "0001045810-24-000029",
-      "primary_document": "nvda-20240128.htm"
-    },
-    {
-      "form_type": "10-Q",
-      "filing_date": "2024-05-22",
-      "accession_number": "0001045810-24-000067",
-      "primary_document": "nvda-20240428.htm"
-    }
-  ],
-  "error": null
-}
-```
-
-**cURL Example:**
-```bash
-curl -X POST "https://your-space-name.hf.space/api/get_company_filings" \
-  -H "Content-Type: application/json" \
-  -d '{"cik": "0001045810", "form_types": ["10-K", "10-Q"]}'
-```
-
-**Python Example:**
-```python
-import requests
-
-url = "https://your-space-name.hf.space/api/get_company_filings"
-payload = {
-    "cik": "0001045810",
-    "form_types": ["10-K", "10-Q"]
-}
-response = requests.post(url, json=payload)
-print(response.json())
-```
-
----
-
-### 4. Get Company Facts
-
-**Endpoint:** `POST /api/get_company_facts`
-
-**Request:**
-```json
-{
-  "cik": "0001045810"
-}
-```
-
-**Response:**
-```json
-{
-  "facts": {
-    "dei": {
-      "EntityCommonStockSharesOutstanding": {...},
-      "EntityPublicFloat": {...}
-    },
-    "us-gaap": {
-      "Revenues": {...},
-      "NetIncomeLoss": {...},
-      "EarningsPerShareBasic": {...}
-    }
-  },
-  "error": null
-}
-```
-
-**cURL Example:**
-```bash
-curl -X POST "https://your-space-name.hf.space/api/get_company_facts" \
-  -H "Content-Type: application/json" \
-  -d '{"cik": "0001045810"}'
-```
-
-**Python Example:**
-```python
-import requests
-
-url = "https://your-space-name.hf.space/api/get_company_facts"
-payload = {"cik": "0001045810"}
-response = requests.post(url, json=payload)
-print(response.json())
-```
-
----
-
-### 5. Get Financial Data for Period
-
-**Endpoint:** `POST /api/get_financial_data`
-
-**Request (Annual Data):**
-```json
-{
-  "cik": "0001045810",
-  "period": "2024"
-}
-```
-
-**Request (Quarterly Data):**
-```json
-{
-  "cik": "0001045810",
-  "period": "2024Q3"
-}
-```
-
-**Response:**
-```json
-{
-  "period": "2024",
-  "total_revenue": 60922000000,
-  "net_income": 29760000000,
-  "earnings_per_share": 12.04,
-  "operating_expenses": 11822000000,
-  "operating_cash_flow": 28091000000,
-  "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581024000029",
-  "source_form": "10-K",
-  "data_source": "us-gaap",
-  "additional_details": {
-    "total_revenue_details": {
-      "tag": "Revenues",
-      "form": "10-K",
-      "fy": 2024,
-      "fp": "FY",
-      "val": 60922000000,
-      "start": "2023-01-30",
-      "end": "2024-01-28",
-      "accn": "0001045810-24-000029",
-      "filed": "2024-02-21",
-      "frame": "CY2023",
-      "data_source": "us-gaap"
-    }
-  },
-  "error": null
-}
-```
-
-**cURL Example:**
-```bash
-curl -X POST "https://your-space-name.hf.space/api/get_financial_data" \
-  -H "Content-Type: application/json" \
-  -d '{"cik": "0001045810", "period": "2024"}'
-```
-
-**Python Example:**
-```python
-import requests
-
-url = "https://your-space-name.hf.space/api/get_financial_data"
-payload = {
-    "cik": "0001045810",
-    "period": "2024"
-}
-response = requests.post(url, json=payload)
-data = response.json()
-print(f"Total Revenue: ${data['total_revenue']:,.0f}")
-print(f"Net Income: ${data['net_income']:,.0f}")
-print(f"EPS: ${data['earnings_per_share']:.2f}")
-```
-
----
-
-## Complete Python Client Example
-
-```python
-import requests
-import json
-
-
-class SECMCPClient:
-    """Client for SEC Financial Report MCP Server"""
-    
-    def __init__(self, base_url):
-        self.base_url = base_url.rstrip('/')
-    
-    def search_company(self, company_name):
-        """Search company by name"""
-        url = f"{self.base_url}/api/search_company"
-        response = requests.post(url, json={"company_name": company_name})
-        return response.json()
-    
-    def get_company_info(self, cik):
-        """Get company information"""
-        url = f"{self.base_url}/api/get_company_info"
-        response = requests.post(url, json={"cik": cik})
-        return response.json()
-    
-    def get_company_filings(self, cik, form_types=None):
-        """Get company filings"""
-        url = f"{self.base_url}/api/get_company_filings"
-        payload = {"cik": cik, "form_types": form_types}
-        response = requests.post(url, json=payload)
-        return response.json()
-    
-    def get_company_facts(self, cik):
-        """Get company facts"""
-        url = f"{self.base_url}/api/get_company_facts"
-        response = requests.post(url, json={"cik": cik})
-        return response.json()
-    
-    def get_financial_data(self, cik, period):
-        """Get financial data for period"""
-        url = f"{self.base_url}/api/get_financial_data"
-        payload = {"cik": cik, "period": period}
-        response = requests.post(url, json=payload)
-        return response.json()
-
-
-# Usage example
-if __name__ == "__main__":
-    # Initialize client
-    client = SECMCPClient("https://your-space-name.hf.space")
-    
-    # Search for a company
-    company = client.search_company("NVIDIA")
-    print(f"Found: {company['name']} (CIK: {company['cik']})")
-    
-    # Get company information
-    info = client.get_company_info(company['cik'])
-    print(f"Industry: {info['sic_description']}")
-    
-    # Get recent filings
-    filings = client.get_company_filings(company['cik'], ["10-K"])
-    print(f"Recent 10-K filings: {len(filings['filings'])}")
-    
-    # Get financial data for 2024
-    financial_data = client.get_financial_data(company['cik'], "2024")
-    print(f"FY2024 Revenue: ${financial_data['total_revenue']:,.0f}")
-    print(f"FY2024 Net Income: ${financial_data['net_income']:,.0f}")
-    print(f"FY2024 EPS: ${financial_data['earnings_per_share']:.2f}")
-```
-
----
-
-## Complete JavaScript/Node.js Client Example
-
-```javascript
-const axios = require('axios');
-
-class SECMCPClient {
-    constructor(baseUrl) {
-        this.baseUrl = baseUrl.replace(/\/$/, '');
-    }
-
-    async searchCompany(companyName) {
-        const response = await axios.post(
-            `${this.baseUrl}/api/search_company`,
-            { company_name: companyName }
-        );
-        return response.data;
-    }
-
-    async getCompanyInfo(cik) {
-        const response = await axios.post(
-            `${this.baseUrl}/api/get_company_info`,
-            { cik: cik }
-        );
-        return response.data;
-    }
-
-    async getCompanyFilings(cik, formTypes = null) {
-        const response = await axios.post(
-            `${this.baseUrl}/api/get_company_filings`,
-            { cik: cik, form_types: formTypes }
-        );
-        return response.data;
-    }
-
-    async getCompanyFacts(cik) {
-        const response = await axios.post(
-            `${this.baseUrl}/api/get_company_facts`,
-            { cik: cik }
-        );
-        return response.data;
-    }
-
-    async getFinancialData(cik, period) {
-        const response = await axios.post(
-            `${this.baseUrl}/api/get_financial_data`,
-            { cik: cik, period: period }
-        );
-        return response.data;
-    }
-}
-
-// Usage example
-(async () => {
-    const client = new SECMCPClient('https://your-space-name.hf.space');
-    
-    // Search for a company
-    const company = await client.searchCompany('NVIDIA');
-    console.log(`Found: ${company.name} (CIK: ${company.cik})`);
-    
-    // Get financial data
-    const financialData = await client.getFinancialData(company.cik, '2024');
-    console.log(`FY2024 Revenue: $${financialData.total_revenue.toLocaleString()}`);
-    console.log(`FY2024 Net Income: $${financialData.net_income.toLocaleString()}`);
-    console.log(`FY2024 EPS: $${financialData.earnings_per_share.toFixed(2)}`);
-})();
-```
-
----
-
-## Error Handling
-
-All endpoints return standard HTTP status codes:
-
-- **200 OK**: Successful request
-- **422 Unprocessable Entity**: Invalid request parameters
-- **500 Internal Server Error**: Server error
-
-Error response format:
-```json
-{
-  "detail": "Error message description"
-}
-```
-
-Or for API-specific errors:
-```json
-{
-  "error": "No company found matching 'INVALID_NAME'"
-}
-```
-
----
-
-## Notes
-
-- All monetary values are in USD (original values, not converted to millions)
-- The `earnings_per_share` value is per share
-- Data source: US SEC EDGAR system
-- Supports US-GAAP and IFRS standards
-- User-Agent: Juntao Peng (jtyxabc@gmail.com)
-- Rate limiting follows SEC EDGAR API guidelines (10 requests per second)
-
----
-
-## Interactive API Documentation
-
-Once deployed, you can access interactive API documentation at:
-
-- Swagger UI: `https://your-space-name.hf.space/docs`
-- ReDoc: `https://your-space-name.hf.space/redoc`