Metadata-Version: 2.4
Name: ossctx
Version: 0.1.0b5
Summary: Unified Python CLI for code, docs, and otel context tooling
Author: RandomCodeSpace
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: alembic>=1.13.2
Requires-Dist: fastapi>=0.115.0
Requires-Dist: grpcio>=1.71.0
Requires-Dist: httpx>=0.27.2
Requires-Dist: jinja2>=3.1.4
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-ollama>=0.2.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: opentelemetry-proto>=1.31.0
Requires-Dist: protobuf>=5.29.0
Requires-Dist: pydantic-settings[yaml]>=2.5.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: sqlalchemy>=2.0.35
Requires-Dist: starlette>=0.41.0
Requires-Dist: typer[all]>=0.12.5
Requires-Dist: uvicorn[standard]>=0.31.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11.2; extra == 'dev'
Requires-Dist: pip-audit>=2.7.3; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.3.3; extra == 'dev'
Requires-Dist: ruff>=0.6.9; extra == 'dev'
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter-go>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-java>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-rust>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-typescript>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter>=0.22.3; extra == 'tree-sitter'
Description-Content-Type: text/markdown

# ossctx

`ossctx` is a unified Python toolkit for building local context services around source code, documentation, and telemetry.

It brings three related systems under one CLI and one package:

- `ossCtx code` for source indexing, dependency analysis, call-graph queries, API serving, and MCP access
- `ossCtx docs` for document indexing, website crawling, search, analysis, API serving, and MCP access
- `ossCtx otel` for trace/log/metric ingestion, observability APIs, OTLP compatibility, and MCP access

The goal is to provide a consistent local operator workflow for indexing information, exposing it through HTTP and MCP, and integrating it into editor and agent tooling.

## Project structure

The package is organized into four top-level Python packages:

- `common` contains shared CLI, config, database, middleware, and server helpers
- `codectx` implements code indexing and graph queries
- `docsctx` implements document ingestion, crawling, analysis, and retrieval
- `otelctx` implements telemetry ingestion, storage, search, and service graph features

## Features

### Code context

- Index local source trees into SQLite
- Extract entities, dependencies, and relations
- Query entities, file dependencies, and call graphs
- Run an HTTP API server for indexed code data
- Run or configure an MCP server for editor and agent integrations
- Install compatibility alias: `codecontext`

### Document context

- Index local text, markdown, and HTML content
- Crawl documentation sites from a root URL
- Chunk and persist document content
- Run deterministic or provider-backed finalize analysis
- Search indexed content and inspect communities/entities through HTTP APIs
- Run or configure an MCP server for document search workflows
- Install compatibility alias: `docscontext`

### Telemetry context

- Ingest traces, logs, and metrics from JSON payloads
- Support OTLP HTTP JSON compatibility routes
- Support OTLP gRPC ingestion when dependencies are available
- Query traces, logs, metrics, services, archive, DLQ, TSDB, and health data via HTTP APIs
- Expose websocket and optional Prometheus integrations
- Run or configure an MCP server for observability workflows
- Install compatibility alias: `otelcontext`

## Requirements

- Python `>=3.11`
- Windows, macOS, or Linux with a working Python environment

## Installation

Install from the repo root using [`uv`](https://github.com/astral-sh/uv):

```bash
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
```

Install with development extras:

```bash
uv pip install -e ".[dev]"
```

Install with optional parser and loader support:

```bash
uv pip install -e ".[dev,tree-sitter,loaders]"
```

## Running

You can use `uv run` to execute the CLI commands without explicitly activating the virtual environment:

```bash
# Run the main CLI
uv run ossCtx --help

# Serve the UI
uv run ossCtx ui serve

# Run specific contexts
uv run ossCtx code --help
uv run ossCtx docs --help
uv run ossCtx otel --help
```

Optional extras:

- `dev` adds pytest, ruff, mypy, and pip-audit
- `tree-sitter` adds higher-fidelity parsers for supported languages
- `loaders` adds PDF and Word document ingestion support

## Installed commands

Primary entrypoint:

- `ossCtx`

Compatibility aliases:

- `codecontext`
- `docscontext`
- `otelcontext`

Version command:

```bash
ossCtx --version
```

## Quickstart

### Index code

```bash
ossCtx code index . --db .codecontext.db
ossCtx code stats --db .codecontext.db
ossCtx code query entity hello --db .codecontext.db
```

### Index documents

```bash
ossCtx docs index ./docs --db .docscontext.db --finalize
ossCtx docs stats --db .docscontext.db
ossCtx docs serve --db .docscontext.db --port 8090
```

### Crawl a documentation website

```bash
ossCtx docs index --url https://example.com/docs --db .docscontext.db --max-pages 100 --max-depth 2 --finalize
```

### Ingest telemetry

```bash
ossCtx otel ingest traces.json --db .otelcontext.db
ossCtx otel stats --db .otelcontext.db
ossCtx otel serve --db .otelcontext.db --http-port 8088 --grpc-port 4317
```

## Default storage and ports

Default SQLite files:

- Code: `.codecontext.db`
- Docs: `.docscontext.db`
- Otel: `.otelcontext.db`

Default API ports:

- Code: `8080`
- Docs: `8090`
- Otel HTTP: `8088`
- Otel gRPC: `4317`

Default Otel archive directory:

- `.otel_archive`

## Command reference

### Root CLI

```bash
ossCtx --version
ossCtx code ...
ossCtx docs ...
ossCtx otel ...
```

### Code commands

#### `ossCtx code index`

Index a directory into the code database.

```bash
ossCtx code index <path> [--db PATH] [--max-file-size MB]
```

Important options:

- `--db` overrides the SQLite path
- `--max-file-size` skips very large files during indexing

#### `ossCtx code query`

Query indexed code data.

```bash
ossCtx code query entity <name> [--db PATH]
ossCtx code query deps <file-path> [--db PATH]
ossCtx code query calls <entity-name> [--db PATH]
```

Query types:

- `entity` finds matching entities by name
- `deps` prints file dependency information
- `calls` prints outgoing and incoming call edges

#### `ossCtx code stats`

Show code index statistics.

```bash
ossCtx code stats [--db PATH]
```

#### `ossCtx code clean`

Delete the code database and SQLite sidecar files.

```bash
ossCtx code clean [--db PATH]
```

#### `ossCtx code serve`

Run the code HTTP API server.

```bash
ossCtx code serve [--host HOST] [--port PORT] [--db PATH]
```

#### `ossCtx code mcp`

Run the CodeCtx MCP server.

```bash
ossCtx code mcp [--transport stdio|sse|streamable-http] [--addr HOST:PORT] [--db PATH]
```

Examples:

```bash
ossCtx code mcp --transport stdio --db .codecontext.db
ossCtx code mcp --transport streamable-http --addr 127.0.0.1:8081 --db .codecontext.db
ossCtx code mcp --transport sse --addr 127.0.0.1:8081 --db .codecontext.db
```

#### `ossCtx code setup`

Write or update a VS Code MCP config entry for CodeCtx.

```bash
ossCtx code setup [--binary BIN] [--transport TYPE] [--addr HOST:PORT] [--db PATH] [--output PATH] [--server-name NAME]
```

Example:

```bash
ossCtx code setup --output .vscode/mcp.json --db .codecontext.db
```

### Docs commands

#### `ossCtx docs index`

Index local files or crawl a documentation site.

```bash
ossCtx docs index <path> [--db PATH] [--chunk-size N] [--chunk-overlap N] [--finalize]
ossCtx docs index --url URL [--db PATH] [--max-pages N] [--max-depth N] [--allow-external] [--same-path-prefix|--no-same-path-prefix] [--timeout SECONDS] [--finalize]
```

Important options:

- `--url` crawls from a root site instead of indexing a local path
- `--chunk-size` and `--chunk-overlap` tune chunking behavior
- `--max-pages` and `--max-depth` control crawl size
- `--allow-external` allows following links outside the root host
- `--same-path-prefix` restricts crawling to the original path prefix
- `--finalize` runs structure/entity/community analysis after ingest

#### `ossCtx docs stats`

Show document index statistics.

```bash
ossCtx docs stats [--db PATH] [--json]
```

#### `ossCtx docs serve`

Run the DocsCtx HTTP API server.

```bash
ossCtx docs serve [--host HOST] [--port PORT] [--db PATH]
```

#### `ossCtx docs mcp`

Run the DocsCtx MCP server.

```bash
ossCtx docs mcp [--transport stdio|sse|streamable-http] [--db PATH]
```

#### `ossCtx docs setup`

Write or update a VS Code MCP config for DocsCtx.

```bash
ossCtx docs setup [--output PATH] [--transport TYPE]
```

### Otel commands

#### `ossCtx otel ingest`

Ingest a JSON payload file containing traces, logs, metrics, or OTLP-compatible payloads.

```bash
ossCtx otel ingest <path> [--db PATH]
```

#### `ossCtx otel stats`

Show telemetry statistics.

```bash
ossCtx otel stats [--db PATH]
```

#### `ossCtx otel serve`

Run the OtelCtx HTTP API server and optional OTLP gRPC receiver.

```bash
ossCtx otel serve [--host HOST] [--http-port PORT] [--grpc-port PORT] [--db PATH]
```

Notes:

- HTTP API defaults to port `8088`
- OTLP gRPC defaults to port `4317`
- If gRPC dependencies are unavailable, the HTTP server can still run

#### `ossCtx otel mcp`

Run the OtelCtx MCP server.

```bash
ossCtx otel mcp [--transport stdio|sse|streamable-http] [--addr HOST:PORT] [--db PATH]
```

#### `ossCtx otel setup`

Write or update a VS Code MCP config entry for OtelCtx.

```bash
ossCtx otel setup [--binary BIN] [--transport TYPE] [--addr HOST:PORT] [--db PATH] [--output PATH] [--server-name NAME]
```

## MCP workflows

Each subsystem can run as an MCP server or generate a VS Code MCP config file.

Common patterns:

```bash
ossCtx code mcp --transport stdio
ossCtx docs mcp --transport stdio
ossCtx otel mcp --transport stdio
```

Generate `.vscode/mcp.json` entries:

```bash
ossCtx code setup --output .vscode/mcp.json
ossCtx docs setup --output .vscode/mcp.json
ossCtx otel setup --output .vscode/mcp.json
```

Transport modes:

- `stdio` for local process-based MCP integration
- `sse` for HTTP SSE transport where supported
- `streamable-http` for HTTP MCP endpoints where supported

## Supported content and formats

### Code parsing

The parser registry supports a broad set of source and config formats, including:

- Python
- Go
- JavaScript and TypeScript
- Java
- Rust
- C#
- Ruby
- SQL
- Kotlin
- Scala
- Bash
- Lua
- Perl
- R
- HTML
- CSS
- Markdown
- JSON
- XML
- YAML
- TOML
- HCL
- Properties
- Dockerfile

Installing the `tree-sitter` extra improves fidelity for supported languages.

### Document formats

Built-in local document loading supports:

- `.txt`
- `.text`
- `.md`
- `.markdown`
- `.html`
- `.htm`

Optional loader extras add:

- PDF via `pymupdf`
- Word documents via `python-docx`

## API overview

### Code API

Run it with:

```bash
ossCtx code serve --db .codecontext.db
```

It exposes shared health/version endpoints plus codectx routes for stats, file/entity lookup, dependency graphs, and call-graph access.

### Docs API

Run it with:

```bash
ossCtx docs serve --db .docscontext.db
```

It exposes shared health/version endpoints plus document listing, retrieval, versions, upload, search, finalize, upload progress, communities, entities, and graph neighborhood routes.

### Otel API

Run it with:

```bash
ossCtx otel serve --db .otelcontext.db
```

It exposes shared health/version endpoints plus traces, logs, metrics, services, dashboard, archive, DLQ, sampler, graph, ingest, OTLP compatibility, and websocket routes.

## Configuration

The package uses environment-driven settings via Pydantic settings models.

Useful environment variables include:

### CodeCtx

- `CODECTX_DB_PATH`
- `CODECTX_HOST`
- `CODECTX_PORT`
- `CODECTX_MAX_FILE_SIZE_MB`

### DocsCtx

- `DOCSCTX_DB_PATH`
- `DOCSCTX_HOST`
- `DOCSCTX_PORT`
- `DOCSCTX_CHUNK_SIZE`
- `DOCSCTX_CHUNK_OVERLAP`
- `DOCSCTX_MAX_PAGES`
- `DOCSCTX_MAX_DEPTH`
- `DOCSCTX_LLM_PROVIDER`
- `DOCSCTX_LLM_MODEL`
- `DOCSCTX_LLM_BASE_URL`
- `DOCSCTX_LLM_API_KEY`
- `DOCSCTX_LLM_TIMEOUT_SECONDS`
- `DOCSCTX_LLM_MAX_RETRIES`
- `DOCSCTX_LLM_RETRY_BACKOFF_SECONDS`
- `DOCSCTX_LLM_FALLBACK_ON_ERROR`
- `DOCSCTX_EMBED_MODEL`
- `DOCSCTX_EMBED_BASE_URL`
- `DOCSCTX_EMBED_API_KEY`
- `DOCSCTX_EMBED_BATCH_SIZE`

### OtelCtx

- `OTELCTX_DB_PATH`
- `OTELCTX_HOST`
- `OTELCTX_PORT`
- `OTELCTX_GRPC_PORT`
- `OTELCTX_ARCHIVE_DIR`
- `OTELCTX_HOT_DAYS`
- `OTELCTX_TSDB_CAPACITY`
- `OTELCTX_SAMPLING_RATE`
- `OTELCTX_SAMPLING_ALWAYS_ERRORS`
- `OTELCTX_SAMPLING_LATENCY_THRESHOLD_MS`
- `OTELCTX_DLQ_MAX_RETRIES`
- `OTELCTX_DLQ_REPLAY_INTERVAL_SECONDS`
- `OTELCTX_WS_BUFFER_SIZE`
- `OTELCTX_WS_FLUSH_INTERVAL_MS`
- `OTELCTX_PROMETHEUS_ENABLED`

## Development

Run tests:

```bash
python -m pytest -q
```

Verified test command in the current environment:

```bash
d:/Development/omni-agents/.venv/Scripts/python.exe -m pytest -q
```

Useful development tasks:

```bash
python -m pip install -e .[dev,tree-sitter,loaders]
python -m pytest -q
ruff check .
mypy .
```

## Publishing notes

The package metadata declares:

- project name: `ossctx`
- version: `0.1.0`
- license: MIT
- console scripts: `ossCtx`, `codecontext`, `docscontext`, `otelcontext`

## License

This project is licensed under the MIT License. See `LICENSE`.


