Perceive Content
POST /api/agents/perceive/content
Analyze raw text content with perception capabilities.
Performs analysis on provided text content including entity extraction, sentiment analysis, and strategic insights without needing to fetch from a URL.
Process:
- Analyze provided text content
- Extract entities (people, places, concepts)
- Analyze sentiment and tone
- Map relationships between entities
- Generate strategic insights
Args: request: ContentPerceptionRequest with text content and analysis options
Returns: WebpagePerceptionResponse with analysis results
Raises: HTTPException 400: Invalid content or parameters HTTPException 502: Upstream AI provider returned an empty or schema-invalid extraction response (see detail) HTTPException 503: Lagan agent not available HTTPException 504: LLM did not respond within the configured timeout
Request Body required
Section titled “Request Body required ”Request model for analyzing raw text content.
Analyzes raw text content (plain text, HTML, or markdown) for entity extraction, sentiment analysis, and insights without requiring a URL fetch.
Fields:
content: Text content to analyze (required, non-empty)content_type: Type of content being analyzed (text, html, markdown)depth: Analysis depth level (surface, analytical, strategic)
Usage: Used for analyzing content that’s already available without web fetching.
Integration:
- PerceptionRoutes: Request validation for /perception/content endpoint
- Document Analysis: Local content analysis workflows
object
Text content to analyze
Type of content being analyzed
Analysis depth level
Responses
Section titled “ Responses ”Successful Response
Response model for webpage perception analysis.
Contains extracted entities, relationships, sentiment analysis, and strategic insights from the analyzed webpage. Provides comprehensive perception results for downstream processing and visualization.
Fields:
success: Whether the analysis completed successfullyurl: URL that was analyzedentities: List of extracted entities from contentrelationships: List of entity relationshipssentiment: Sentiment analysis results (optional)strategic_insights: List of strategic insights derived from contentcontent_summary: Brief summary of page contentmetadata: Additional metadata (title, author, publication date, etc.)processing_time_ms: Total processing time in millisecondstiming: Per-phase timing breakdown (knowledge vs extraction)extraction_retries: How many schema-violation retries the extraction call burned before producing valid output (0 on first-try success)
Usage: Returned by perception endpoints after webpage analysis.
Integration:
- PerceptionRoutes: Response model for /perception/webpage endpoint
- Frontend: Perception results display and visualization
- Knowledge Base: Entity and relationship storage
object
Whether analysis was successful
URL that was analyzed
Extracted entities from content
Extracted entity from content with type classification and confidence scoring.
Represents a named entity (person, place, organization, concept, etc.) extracted from analyzed content with confidence scoring and contextual information.
Fields:
name: Entity name or identifier as extracted from contententity_type: Classification type (person, place, organization, concept, etc.)confidence: Extraction confidence score from 0.0 to 1.0context: Surrounding text context where entity was found
Usage: Used in perception and research responses to return extracted entities.
Integration:
- WebpagePerceptionResponse: Entity list in perception results
- ResearchResult: Entities extracted from research results
- EnrichContentResponse: Additional entities from enrichment
Relationships between entities
Relationship between two extracted entities.
Represents a directional relationship between two entities with type classification and confidence scoring. Used for building knowledge graphs and understanding entity interconnections.
Fields:
from_entity: Source entity name in the relationshipto_entity: Target entity name in the relationshiprelationship_type: Type/nature of the relationshipconfidence: Relationship confidence score from 0.0 to 1.0
Usage: Used in perception responses to map entity relationships.
Integration:
- WebpagePerceptionResponse: Relationship list in perception results
- Knowledge Graph: Entity relationship visualization
object
Source entity in relationship
Target entity in relationship
Type of relationship
Relationship confidence
Sentiment analysis results for analyzed content.
Provides comprehensive sentiment scoring including overall sentiment classification, confidence scoring, detected tones, and emotional indicators for nuanced content understanding.
Fields:
overall_sentiment: Primary sentiment classification (positive, neutral, negative)confidence: Sentiment classification confidence scoretone: List of detected tones (professional, casual, technical, etc.)emotional_indicators: Dictionary of emotional indicators with strength scores
Usage: Used in perception responses to provide sentiment analysis results.
Integration:
- WebpagePerceptionResponse: Sentiment field in perception results
- Frontend: Sentiment visualization and indicators
object
Overall content sentiment
Sentiment confidence score
Detected tones (professional, casual, etc.)
Emotional indicators with strength scores
object
Strategic insights derived from content
Additional metadata (title, author, date, etc.)
object
Processing time in milliseconds
Per-phase timing breakdown for a perception run.
Splits the total pipeline duration into its two dominant phases so users and UIs can diagnose which stage is slow:
knowledge_ms: Lagan’s knowledge-request collection (web fetch + streaming analysis) — typically the bulk of the time.extract_ms: the structured-extraction LLM call that parses the Lagan output into entities / relationships / sentiment.total_ms: wall-clock from endpoint entry to response build.
knowledge_ms + extract_ms may be slightly less than total_ms
because the small entity-merge + response-build work is counted only
under total_ms.
object
Milliseconds spent collecting Lagan’s knowledge-request stream.
Milliseconds spent on the structured-extraction LLM call.
Total wall-clock milliseconds for the perception run.
Number of schema-violation retries the extraction call burned before producing valid output. 0 = succeeded on first attempt.
Validation Error