readme and usage

Author: nicoloboschi

README.md

@@ -307,14 +307,84 @@ vectorize-iris large-document.pdf \
 
 ## Configuration
 
-Set your API credentials:
+### CLI Configuration
 
+The CLI offers multiple ways to configure your credentials:
+
+#### Interactive Configuration (Recommended)
+
+The easiest way to get started - opens your browser for authentication:
+
+```bash
+vectorize-iris configure
+```
+
+**What happens:**
+1. Opens your browser to the Vectorize platform
+2. Click "Authorize" to grant access
+3. Credentials are automatically saved to `~/.vectorize-iris/credentials`
+4. Done! You're ready to extract
+
+#### Manual Configuration
+
+If you prefer not to use the browser, prompt for credentials manually:
+
+```bash
+vectorize-iris configure --manual
+```
+
+You'll be asked to enter:
+- API Token
+- Organization ID
+
+Get these from [platform.vectorize.io](https://platform.vectorize.io) → Account → Org Settings → Access Tokens
+
+#### Non-Interactive Configuration
+
+For scripts and automation, pass credentials directly:
+
+```bash
+vectorize-iris configure --api-token "your-token" --org-id "your-org-id"
+```
+
+#### Environment Variables
+
+Alternatively, set credentials via environment variables (works for all clients):
+
+```bash
+export VECTORIZE_TOKEN="your-token"
+export VECTORIZE_ORG_ID="your-org-id"
+```
+
+### Python & Node.js Configuration
+
+For Python and Node.js clients, use environment variables or pass credentials programmatically:
+
+**Environment variables:**
 ```bash
 export VECTORIZE_TOKEN="your-token"
 export VECTORIZE_ORG_ID="your-org-id"
 ```
 
-Get your credentials at [Vectorize Console](https://vectorize.io).
+**Python:**
+```python
+from vectorize_iris import VectorizeIrisClient
+
+client = VectorizeIrisClient(
+    api_token="your-token",
+    org_id="your-org-id"
+)
+```
+
+**Node.js:**
+```typescript
+import { extractTextFromFile } from '@vectorize-io/iris';
+
+const result = await extractTextFromFile('document.pdf', {
+    apiToken: 'your-token',
+    orgId: 'your-org-id'
+});
+```
 
 ## Documentation
 

nodejs-api/src/types.ts

@@ -41,6 +41,10 @@ export interface StartExtractionResponse {
   extractionId: string;
 }
 
+export interface UsageInfo {
+  irisPages: number;
+}
+
 export interface ExtractionResultData {
   success: boolean;
   chunks?: string[];
@@ -49,6 +53,7 @@ export interface ExtractionResultData {
   metadataSchema?: string;
   chunksMetadata?: (string | null)[];  // JSON strings, may contain nulls
   chunksSchema?: (string | null)[];  // May contain nulls
+  usage?: UsageInfo;
   error?: string;
 }
 

python-api/vectorize_iris/models.py

@@ -65,6 +65,13 @@ class StartExtractionResponse(BaseModel):
     extraction_id: str = Field(..., alias="extractionId", description="Unique identifier for the extraction job")
 
 
+class UsageInfo(BaseModel):
+    """Usage information for the extraction"""
+    model_config = ConfigDict(populate_by_name=True)
+
+    iris_pages: int = Field(..., alias="irisPages", description="Number of pages processed by Iris")
+
+
 class ExtractionResultData(BaseModel):
     """Data contained in extraction result"""
     model_config = ConfigDict(populate_by_name=True, extra='allow')
@@ -84,6 +91,7 @@ class ExtractionResultData(BaseModel):
         alias="chunksSchema",
         description="Schema IDs used for each chunk's metadata"
     )
+    usage: Optional[UsageInfo] = Field(default=None, description="Usage information")
     error: Optional[str] = Field(default=None, description="Error message if extraction failed")
 
 

rust-cli/src/main.rs

@@ -114,6 +114,12 @@ enum OutputFormat {
 
 // Request/Response Models
 
+#[derive(Deserialize, Serialize)]
+struct UsageInfo {
+    #[serde(rename = "irisPages")]
+    iris_pages: u32,
+}
+
 #[derive(Serialize)]
 struct StartUploadRequest {
     name: String,
@@ -179,6 +185,8 @@ struct ExtractionResultData {
     #[serde(skip_serializing_if = "Option::is_none", rename = "chunksSchema")]
     chunks_schema: Option<Vec<Option<String>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    usage: Option<UsageInfo>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     error: Option<String>,
 }
 
@@ -864,6 +872,18 @@ fn format_output(data: &ExtractionResultData, format: &OutputFormat, has_schemas
                 print_wrapped_text(text, 0);
             }
 
+            // Show usage information if available
+            if let Some(usage) = &data.usage {
+                println!();
+                println!("{}", style("─".repeat(60)).dim());
+                println!("{} {}", CHART, style("Usage Information").cyan().bold());
+                println!();
+                println!("  {} Iris Pages: {}",
+                    style("📄").dim(),
+                    style(usage.iris_pages).cyan().bold()
+                );
+            }
+
             println!();
             println!("{}", style("─".repeat(60)).dim());
             println!("{} {}", SPARKLE, style("Extraction complete!").green().bold());