Metadata-Version: 2.4
Name: hypercontext
Version: 0.1.4
Summary: Self-referential context-aware agent framework advancing ContextFission with meta-cognitive self-modification, evolutionary archive, transfer learning, pluggable provider runtimes, and an optional research-tools extension.
Home-page: https://github.com/rotsl/hypercontext
Author: Rohan R
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/rotsl/hypercontext
Project-URL: Repository, https://github.com/rotsl/hypercontext
Project-URL: Documentation, https://rotsl.github.io/hypercontext/installation/package_py/
Project-URL: Issues, https://github.com/rotsl/hypercontext/issues
Project-URL: Changelog, https://github.com/rotsl/hypercontext/releases
Keywords: ai,agents,context-aware,self-referential,meta-cognitive,hyperagents,context-fission,evolutionary-archive,transfer-learning,provider-runtime,provider-presets,research-tools,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.6; extra == "dev"
Dynamic: license-file


## What is Hypercontext?

Hypercontext is a standalone Python SDK for building AI agents that are **aware of their own context**. Unlike conventional agent frameworks that operate with fixed prompts and static tool sets, Hypercontext agents:

- **Observe their own reasoning** in real time
- **Rewrite their own context** based on performance feedback
- **Archive successful strategies** in an evolutionary knowledge base
- **Transfer learned behaviors** across tasks and sessions

The framework is inspired by the Hyperagents paper's vision of meta-cognitive AI systems — agents that don't just *use* context, but *reason about* and *modify* their own context to improve over time.

## Features

- **Self-Referential Context Loop** — agents read and rewrite their own system prompts, tool descriptions, and memory at runtime
- **Meta-Cognitive Self-Modification** — built-in reflection and context evolution based on task outcomes
- **Evolutionary Archive** — persistent store of proven context configurations, ranked by fitness
- **Transfer Learning** — reuse context patterns across different tasks, domains, and agent instances
- **Context Fission** — intelligent decomposition of complex contexts into specialized sub-contexts (from ContextFission)
- **Zero External Dependencies** — pure Python core; TypeScript SDK with minimal deps
- **Dual SDK** — first-class Python and TypeScript/Node.js support
- **Framework Agnostic** — works with any LLM provider (OpenAI, Anthropic, local models, etc.)
- **Operational Provider Recipes** — practical setup guides and runnable demos for Claude, OpenAI, Ollama, OpenAI-compatible servers, and local models
- **Dedicated TUI** — a curses-based terminal dashboard for browsing, pinning, and executing CLI commands in the shell, with `--workdir` support for project-root workflows
- **MCP Everywhere** — a stdio MCP daemon for Claude Desktop, Claude Code, Codex, and other terminal or desktop agents, plus the existing HTTP server for the browser dashboard
- **Optional Research Tools Extension** — bundled research-session and bounded-experiment tools that stay disabled until you opt in with `HYPERCONTEXT_ENABLE_RESEARCH_TOOLS=1` or `MetaAgent(enable_research_tools=True)`


## What You Get

Installing `hypercontext` from PyPI gives you:

- the Python SDK
- the `python -m hypercontext` CLI
- the dedicated terminal UI
- the bundled stdio MCP daemon
- the bundled HTTP MCP server
- the browser dashboard launcher
- the example-friendly provider runtime and agent APIs

You do not need to install a separate `mcp` package.
This is the full Hypercontext runtime for Python users, not a thin SDK-only
package.

## Coverage At A Glance

| Ships | Does Not Ship |
|---|---|
| Python SDK, CLI, TUI, stdio MCP daemon, HTTP server, browser launcher, provider runtime, agents, memory, scoring, archive, examples, and the optional research-tools extension code | `README.md`, `usage.md`, or the npm SDK |

## Prerequisites

- Python 3.10 or newer
- `pip`
- A virtual environment is strongly recommended

Create a virtual environment if you want to keep the install isolated:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

## Install Hypercontext

Install the published package:

```bash
pip install hypercontext
```

If you want the development extras that match this repository’s toolchain:

```bash
pip install "hypercontext[dev]"
```

The package is designed to be used without needing a local workspace copy.

## Verify The Install

Confirm that the package imports correctly:

```bash
python - <<'PY'
import hypercontext
print("hypercontext version:", hypercontext.__version__)
print("Loaded from:", hypercontext.__file__)
PY
```

Or use the CLI:

```bash
python -m hypercontext version
```

## Package Configuration

Hypercontext reads runtime settings from the process environment.

You only need a `.env` file when you want to set provider credentials,
output directories, token budgets, or other runtime flags. If you do want
one, copy the example template and populate it for your environment:

```bash
cp .env.example .env
```

Key settings include:

- `HYPERCONTEXT_PROVIDER`
- `HYPERCONTEXT_MODEL`
- `HYPERCONTEXT_API_KEY`
- `HYPERCONTEXT_BASE_URL`
- `HYPERCONTEXT_ORGANIZATION`
- `HYPERCONTEXT_TOKEN_BUDGET`
- `HYPERCONTEXT_TEMPERATURE`
- `HYPERCONTEXT_MAX_TOKENS`
- `HYPERCONTEXT_OUTPUT_DIR`
- `HYPERCONTEXT_MAX_GENERATIONS`
- `HYPERCONTEXT_PARENT_SELECTION`
- `HYPERCONTEXT_CAVEMAN_MODE`
- `HYPERCONTEXT_DOCKER_IMAGE`
- `HYPERCONTEXT_SANDBOX_ENABLED`
- `HYPERCONTEXT_CONVERGENCE_CEILING`
- `HYPERCONTEXT_ENABLE_RESEARCH_TOOLS`

### Claude / Anthropic Setup

For Anthropic, use the API root URL:

```bash
HYPERCONTEXT_PROVIDER=anthropic
HYPERCONTEXT_MODEL=claude-sonnet-4-20250514
ANTHROPIC_API_KEY=your-key-here
HYPERCONTEXT_BASE_URL=https://api.anthropic.com
ANTHROPIC_BASE_URL=https://api.anthropic.com
```

The provider helpers normalize an accidental trailing `/v1` suffix, but the
cleanest setup is to keep the root API URL in your environment file.

### Ollama Setup

For a fully local backend, start Ollama and point Hypercontext at the local
server:

```bash
ollama serve
ollama pull llama3

HYPERCONTEXT_PROVIDER=ollama
HYPERCONTEXT_MODEL=llama3
OLLAMA_BASE_URL=http://localhost:11434
```

Then the same package commands, TUI, MCP daemon, browser UI, and agent APIs
all work against the Ollama model you selected. For a full walkthrough, see
[Ollama guide](https://rotsl.github.io/hypercontext/ollama/).

### Named Provider Presets

If you want multiple backends in one project, use named provider presets in a
YAML config file and resolve them with `Settings.create_provider()` or
`LLMClient.from_settings()`.

Example:

```yaml
provider_name: claude-test
provider_presets:
  claude-test:
    provider: anthropic
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    base_url: https://api.anthropic.com
  local-mock:
    provider: mock
    model: demo
    extra_kwargs:
      response_delay: 0.0
```

Hypercontext expands `${VAR}` values from the process environment when loading
YAML config, so you can keep secrets out of the file.

### Optional Research Tools Extension

The research-tools extension ships with the Python package, but it remains
inactive until you opt in. When enabled, it registers its tools through
`ToolRegistry` only.

Enable it with an environment variable:

```bash
HYPERCONTEXT_ENABLE_RESEARCH_TOOLS=1
```

Or enable it directly when constructing a `MetaAgent`:

```python
from hypercontext import MetaAgent

agent = MetaAgent(enable_research_tools=True)
```

If you already have a `Settings` object, you can bootstrap the registry
through it:

```python
from hypercontext import Settings, ToolRegistry

settings = Settings.from_env()
registry = ToolRegistry()
settings.bootstrap_research_tools(registry)
```

The extension is still explicit even when bundled:

- if the flag is off, nothing is registered
- if the flag is on, the tools are added to the agent registry
- if the package is present but not imported, there is still no effect

## CLI Command Reference

The package ships a standard-library CLI:

- `version` prints the package version
- `providers` lists registered provider backends
- `run` executes the evolutionary loop
- `compress` reduces text size
- `validate` checks compression fidelity
- `evaluate` runs benchmark-style evaluation scaffolds
- `archive` inspects archive content
- `benchmark` runs benchmark helpers
- `mcp` launches the stdio MCP daemon for desktop and terminal agents
- `serve` launches the HTTP MCP server for browser integrations
- `ui` launches the browser dashboard
- `tui` opens the dedicated curses terminal UI
- `docker` exercises sandbox-oriented workflows

Examples:

```bash
python -m hypercontext providers
python -m hypercontext run --generations 5 --output-dir ./runs/demo --workdir .
python -m hypercontext mcp --workdir /path/to/project
python -m hypercontext tui --workdir /path/to/project
python -m hypercontext serve --port 8080 --workdir /path/to/project
```

Use `--workdir` whenever you want Hypercontext to operate against a specific
project root instead of the current shell directory.

## Use In Your Own Python Project

Typical imports:

```python
from hypercontext import (
    HyperContext,
    TaskAgent,
    MetaAgent,
    LLMClient,
    ArchiveStore,
    LineageTracker,
    ContextCompressor,
    ContextRetriever,
)
```

### Direct Orchestration

```python
from hypercontext import HyperContext

hc = HyperContext(output_dir="./hypercontext_output")
summary = hc.run(max_generations=3)
print(summary)
```

### Provider-Backed Calls

```python
from hypercontext import LLMClient
from hypercontext.providers import ProviderRegistry

registry = ProviderRegistry.instance()
provider = registry.create(
    "anthropic",
    model="claude-sonnet-4-20250514",
    api_key="your-key-here",
    base_url="https://api.anthropic.com",
)

client = LLMClient(provider=provider)
text, history, metadata = client.complete("Summarize Hypercontext in one sentence.")
print(text)
```

### Agent Workflows

Use `TaskAgent` when you want a repeatable task wrapper, and `MetaAgent` when
you want repository-aware tool use or self-modification workflows.

See the example gallery in the main docs for broader usage patterns.

## Assistant Integrations

For Claude Desktop, Claude Code, Codex, or other MCP-aware assistants, use the
native stdio daemon:

```bash
python -m hypercontext mcp --workdir /path/to/project
```

For browser-style or custom web integrations, use the HTTP server:

```bash
python -m hypercontext serve --port 8080 --workdir /path/to/project
```

For a full guide with install-method-specific integration examples, see
[Integrations](https://rotsl.github.io/hypercontext/integrations/).

## Troubleshooting

If installation fails:

- Confirm that you are using Python 3.10 or newer
- Upgrade `pip`
- Try `pip install hypercontext --no-cache-dir`
- If you are behind a locked-down network, make sure access to PyPI is
  available
- If you are testing a provider-backed workflow, confirm that the provider SDK
  and credentials are installed and exported in your shell

