Skip to main content

Cortexa SDK

Project Overview​

@cortexa/sdk is the TypeScript SDK for Cortexa document ingestion and normalization. It gives TypeScript and Node.js consumers a small, typed integration surface for turning raw document inputs into normalized document structures and for calling a configured Cortexa analysis service over HTTP.

This repository exists at the SDK boundary of the broader Cortexa ecosystem. It helps applications, ingestion jobs, examples, tests, and developer tooling interact with Cortexa without taking ownership of backend analysis, persistence, orchestration, tenancy enforcement, or shared domain contract definitions.

Key Responsibilities​

  • Provide the public TypeScript package interface for SDK consumers.
  • Expose typed document processing helpers for parsing and normalization.
  • Re-export shared document contract types from @cortexa/contracts.
  • Provide an HTTP client for Cortexa service endpoints such as health checks and analysis.
  • Maintain package build configuration and local usage examples.
  • Keep SDK responsibilities separate from backend services, infrastructure, storage, and consuming applications.

Current Status​

Implemented capabilities:

  • Public package entrypoint through src/index.ts.
  • Local document processing flow through processDocument.
  • Parsing from raw document payloads into parsed content.
  • Normalization from parsed content into normalized document output.
  • CortexaClient methods for GET /health and POST /analyze.
  • SDK-local request and response interfaces for service analysis calls.
  • TypeScript build output through tsup.
  • A minimal example under examples/process-document.ts.

Planned or reserved capabilities explicitly documented:

  • src/schemas is reserved for runtime schema definitions, but runtime schemas are not currently implemented.
  • Runtime validation, provider-specific adapters, authentication, retries, persistence, and orchestration are not implemented in the current SDK unless added as explicit future capabilities.

Getting Started​

Start by reviewing package.json, src/index.ts, and examples/process-document.ts.

The package is built as a single TypeScript SDK:

  • Source lives under src.
  • The public source entrypoint is src/index.ts.
  • Build output is generated into dist.
  • Shared document contract types come from the sibling dependency @cortexa/contracts at ../cortexa.contracts.

Common local development commands:

npm install
npm run build
npm run dev

Use npm run build to compile the SDK with declaration output. Use npm run dev to run the tsup watch build.

Documentation​

The repository documentation corpus starts here and continues under docs/:

  • docs/ARCHITECTURE.md: architectural source of truth for system responsibilities, boundaries, ecosystem role, design principles, and constraints.
  • docs/REPOSITORY.md: repository organization source of truth for folder responsibilities, package structure, dependency direction, and code placement guidance.

Additional long-lived documentation should live under docs/ when it provides focused guidance without duplicating architecture, repository organization, or source code details.

Architecture Summary​

The SDK is intentionally thin. Its public package layer re-exports supported modules, its processing layer coordinates parsing and normalization, and its client layer isolates HTTP access to an external Cortexa service.

The repository depends on @cortexa/contracts for shared domain document types. It does not own canonical domain models, backend analysis behavior, persistence, queues, deployment infrastructure, authentication policy, or service orchestration.

For architectural details, read docs/ARCHITECTURE.md.

Repository Organization Summary​

This is a single-package TypeScript SDK. Source code lives under src, examples live under examples, and documentation lives under docs. Root configuration files define package metadata, TypeScript settings, dependency locking, and build behavior.

Use docs/REPOSITORY.md for repository navigation, folder ownership, module responsibilities, and guidance on where new code belongs.

Contributing​

Before making structural or externally visible changes, read the architecture and repository guides. Keep changes aligned with the SDK boundary and prefer the existing package patterns.

When contributing:

  • Import through the SDK package entrypoint when consuming public SDK behavior.
  • Keep shared domain contract changes in @cortexa/contracts rather than duplicating them here.
  • Keep HTTP service access isolated in client modules.
  • Keep parsing, normalization, and processing responsibilities separated.
  • Update documentation when package exports, repository structure, ownership boundaries, or code placement conventions change.

Documentation Philosophy​

README.md is the repository entrypoint. It should remain the easiest document to read and should help humans and AI systems quickly understand what this repository is, why it exists, and where to go next.

docs/ARCHITECTURE.md is the architectural source of truth. docs/REPOSITORY.md is the repository organization source of truth. Detailed and focused documentation belongs under docs/.

Documentation Standards​

  • Keep this README concise and summary-oriented.
  • Prefer links to detailed documents over duplicating their content.
  • Avoid large implementation inventories, detailed folder trees, API references, database documentation, and deep architectural explanations.
  • Keep documentation aligned with the implementation and the repository's SDK boundary.