schematico 0.1.0__tar.gz

schematico-0.1.0/.env.example

@@ -0,0 +1,31 @@
+# Copy this file to `.env` and fill in the values you need.
+# Schematico auto-loads `.env` from the current directory.
+
+# ── LLM credentials ───────────────────────────────────────────────────────────
+# Schematico's default model is gateway/anthropic:claude-sonnet-4-6, routed
+# through the Pydantic AI Gateway. Set this to use it.
+PYDANTIC_AI_GATEWAY_API_KEY=
+
+# Optional: override the default model. Any pydantic-ai model string works, e.g.
+#   anthropic:claude-sonnet-4-6
+#   gateway/openai:gpt-4.1
+#   ollama:llama3.2   (local, keyless)
+PAI_MODEL=
+
+# If you'd rather hit a provider directly instead of the gateway, set its native
+# key and point PAI_MODEL at that provider (e.g. anthropic:claude-sonnet-4-6).
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+
+# ── Discover mode (live web search) ───────────────────────────────────────────
+# Required for `schematico discover`. Free tier at https://tavily.com.
+TAVILY_API_KEY=
+
+# ── Observability (optional) ──────────────────────────────────────────────────
+# A Logfire write token. If set, traces, tool calls, and token usage are sent to
+# https://pydantic.dev/logfire. Leave blank to log to stderr only.
+LOGFIRE_TOKEN=
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+# WARNING (default), INFO, or DEBUG. Controls stderr verbosity.
+LOG_LEVEL=WARNING

schematico-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Something isn't working the way you expected
+title: "[Bug] "
+labels: bug
+---
+
+**What happened?**
+A clear description of the bug.
+
+**What did you expect to happen?**
+
+**Steps to reproduce**
+1. ...
+2. ...
+
+If it helps, include the schema you used and the exact command:
+
+```json
+{ "table": "...", "fields": [ ... ] }
+```
+
+```bash
+schematico discover ...
+```
+
+**Environment**
+- schematico version: <!-- pip show schematico -->
+- Python version:
+- OS:
+- Mode: generate / discover
+- Model: <!-- e.g. gateway/anthropic:claude-sonnet-4-6 -->
+
+**Logs**
+Re-run with `LOG_LEVEL=DEBUG` and paste any relevant output (redact API keys!).

schematico-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: "[Feature] "
+labels: enhancement
+---
+
+**What problem are you trying to solve?**
+Describe the use case. The *why* helps us design the right thing.
+
+**Proposed solution**
+What you'd like to see. Rough is fine.
+
+**Alternatives you've considered**
+
+**Anything else?**
+Mockups, example schemas, links to similar tools, etc.

schematico-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## What does this PR do?
+
+<!-- A short summary of the change and the problem it solves. -->
+
+## Why?
+
+<!-- Context / motivation. Link any related issue: Closes #123 -->
+
+## Checklist
+
+- [ ] Tests pass locally (`uv run pytest`)
+- [ ] Code is formatted (`uv run black .`)
+- [ ] Added/updated tests for the change
+- [ ] Updated docs/README if behavior changed

schematico-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+# Publishes to PyPI and creates a GitHub Release when a version tag (e.g. v0.1.0)
+# is pushed. Uses PyPI Trusted Publishing (OIDC) — no API token or secret needed.
+#
+# Typical release flow:
+#   1. Bump `version` in pyproject.toml and merge to main.
+#   2. git tag v0.1.0 && git push origin v0.1.0
+# The tag must match the version in pyproject.toml, or the run fails.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and publish schematico
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/schematico
+    permissions:
+      id-token: write # Trusted Publishing to PyPI (OIDC)
+      contents: write # create the GitHub Release
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uv run python -c 'import schematico; print(schematico.__version__)')"
+          echo "tag=$tag_version  package=$pkg_version"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "::error::Tag v$tag_version does not match pyproject version $pkg_version. Bump the version in pyproject.toml before tagging."
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

schematico-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Check formatting
+        run: uv run black --check .

schematico-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+output/
+output_files/
+.schematico
+output.json

schematico-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Schematico
+
+First off — thank you. Schematico is young and open, and every issue, idea, and
+pull request genuinely helps. This guide will get you from clone to PR in a few
+minutes.
+
+## Ways to contribute
+
+- **Report a bug** — open an issue with steps to reproduce.
+- **Request a feature** — open an issue describing the problem you're trying to
+  solve (the *why* matters more than the *how*).
+- **Improve the docs** — typos, clearer examples, and better explanations are
+  always welcome.
+- **Write code** — pick up an open issue, or propose a change. For anything
+  large, open an issue first so we can agree on direction before you invest time.
+
+## Development setup
+
+Schematico uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+git clone https://github.com/Sententia-Lab/schematico.git
+cd schematico
+uv sync                       # installs the package + dev tools into .venv
+
+cp .env.example .env          # add any keys you need (most tests need none)
+```
+
+## Running the tests
+
+```bash
+uv run pytest                 # the full suite — runs in ~2s, no API keys needed
+```
+
+The test suite mocks the LLM, so you don't need credentials or network access to
+run it. Please add tests for any new behavior.
+
+## Code style
+
+```bash
+uv run black .                # format before committing
+```
+
+- Keep functions small and typed — the codebase uses modern type hints throughout.
+- Match the style of the surrounding code.
+- New public functions get a short docstring.
+
+## Submitting a pull request
+
+1. Fork the repo and create a branch off `main`
+   (`git checkout -b feature/my-change`).
+2. Make your change, with tests, and run `uv run pytest` + `uv run black .`.
+3. Write a clear PR description: what changed, and why.
+4. Open the PR against `main`. CI runs the test suite on every PR.
+
+We aim to review PRs promptly. Small, focused PRs get merged fastest.
+
+## Reporting security issues
+
+Please **do not** open a public issue for security vulnerabilities. Email
+[narenchaudhry@gmail.com](mailto:narenchaudhry@gmail.com) instead, and we'll
+work with you on a fix and disclosure timeline.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[MIT License](LICENSE) that covers the project.

schematico-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naren Chaudhry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schematico-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: schematico
+Version: 0.1.0
+Summary: Generate realistic synthetic data from a simple JSON schema — library + CLI
+Project-URL: Homepage, https://github.com/Sententia-Lab/schematico
+Project-URL: Repository, https://github.com/Sententia-Lab/schematico
+Project-URL: Issues, https://github.com/Sententia-Lab/schematico/issues
+Author-email: Naren Chaudhry <narenchaudhry@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,data-discovery,data-generation,pydantic-ai,schema,synthetic-data,test-data,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: logfire>=3.0.0
+Requires-Dist: pydantic-ai>=0.4.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tavily-python>=0.7.26
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" alt="Schematico" width="110" />
+</p>
+
+<h1 align="center">Schematico</h1>
+
+<p align="center">
+  <strong>Describe the data you want. Get it back as clean JSON.</strong><br/>
+  Find real public records on the live web, or synthesize realistic ones — from one tiny schema.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/schematico/"><img src="https://img.shields.io/pypi/v/schematico.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/schematico/"><img src="https://img.shields.io/pypi/pyversions/schematico.svg" alt="Python versions"></a>
+  <a href="https://github.com/Sententia-Lab/schematico/actions/workflows/test.yml"><img src="https://github.com/Sententia-Lab/schematico/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+---
+
+## Why Schematico exists
+
+Schematico started with a frustration: the public data I needed was *out there*,
+but never in a form I could use. Congressional race results, public filings,
+sports stats, niche reference tables — scattered across a dozen sites, trapped in
+HTML, or sitting behind a paywall. Getting a clean table meant hours of copy-paste,
+fragile scrapers, and manual cleanup.
+
+So I built a tool where you describe the shape of the data you want — once, in a
+few lines — and let an AI agent go **find it on the live web** and hand it back as
+structured JSON. And when no real data exists yet (you're seeding a dev database,
+writing tests, building a demo), the same schema can **synthesize** realistic
+records instead.
+
+One schema. Two ways to fill it.
+
+| Mode | What it does | Needs |
+|---|---|---|
+| **`discover`** | An AI agent searches the live web (via [Tavily](https://tavily.com)) and returns **real** records matching your schema. | LLM key + `TAVILY_API_KEY` |
+| **`generate`** | An LLM **synthesizes** realistic, coherent records from your schema — no web access, fully made-up data. | LLM key |
+
+> Both modes are LLM-backed. Output is always validated against your schema and
+> de-duplicated before you get it.
+
+---
+
+## Install
+
+```bash
+pipx install schematico   # as a CLI tool
+uv add schematico         # as a library
+pip install schematico    # the classic way
+```
+
+---
+
+## Quick start (CLI)
+
+```bash
+# 1. Point Schematico at a model. The default routes Claude through the
+#    Pydantic AI Gateway — set its key (or see "Bring your own models" below).
+export PYDANTIC_AI_GATEWAY_API_KEY=...
+
+# 2. For discover mode, add a Tavily key (free tier at https://tavily.com).
+export TAVILY_API_KEY=...
+
+# 3. Create a project interactively. You'll be prompted for mode, schema,
+#    output dir, count, and model. State lives in ./.schematico/.
+schematico new
+
+# 4. Run it.
+schematico discover     # find real records on the web
+# or
+schematico generate     # synthesize records
+```
+
+Output is written to `./.schematico/output/<project>_<timestamp>.json` by default.
+Override per run with `--output FILE_OR_DIR` and `--count N`.
+
+### Command reference
+
+```
+schematico new                     # interactive project wizard
+schematico list                    # all saved project configs
+schematico generate [--config N]   # synthesize records (uses default project)
+schematico discover [--config N]   # find real records on the web
+schematico delete NAME             # delete a config (-m to disambiguate mode)
+schematico help                    # the full command tree, every flag
+```
+
+Common flags on `generate` / `discover`: `--config/-c`, `--output/-o`,
+`--count/-n`, `--model/-m`.
+
+---
+
+## Schema format
+
+A schema is a small JSON object describing the table you want:
+
+```json
+{
+  "table": "congressional_elections",
+  "rows": 50,
+  "instructions": "U.S. House races in the 2026 midterms.",
+  "fields": [
+    { "name": "district",        "type": "string", "description": "state and district, e.g. 'CA-12'" },
+    { "name": "election_date",   "type": "string", "description": "ISO 8601 date" },
+    { "name": "incumbent_party", "type": "enum",   "values": ["D", "R", "I"] },
+    { "name": "is_open_seat",    "type": "bool" }
+  ]
+}
+```
+
+| Top-level key | Required | Meaning |
+|---|---|---|
+| `table` | ✅ | Name of the table (also names the output model). |
+| `fields` | ✅ | List of field definitions (see below). |
+| `rows` | — | How many records to produce (default `25`). |
+| `instructions` | — | Free-text guidance passed to the agent. |
+
+### Field types
+
+Types are deliberately minimal — the **`description`** does the heavy lifting.
+
+| Type | Python | Notes |
+|---|---|---|
+| `string` | `str` | Any text. Shape it with `description`, e.g. `"UUID v4"`, `"ISO 8601 timestamp"`, `"ISO 3166 country code"`. |
+| `int` | `int` | Optional `min` / `max`. |
+| `float` | `float` | Optional `min` / `max`. |
+| `bool` | `bool` | `true` / `false`. |
+| `enum` | one of `values` | Requires a non-empty `values` list. |
+
+> There's no dedicated `uuid` / `email` / `timestamp` type on purpose. Use
+> `string` and say what you want in `description` — the model fills it in
+> accordingly, and you're never boxed in by a fixed type list.
+
+---
+
+## Library usage
+
+Define a schema as a Pydantic model and call `run_generation` or `run_discovery`:
+
+```python
+from pydantic import BaseModel, Field
+from schematico import run_generation
+
+class User(BaseModel):
+    id: str = Field(description="UUID v4")
+    full_name: str = Field(description="realistic full name")
+    email: str = Field(description="work email matching the name")
+    role: str = Field(description="one of: admin, editor, viewer")
+
+records = run_generation(
+    User,
+    samples=10,
+    instructions="EU-based users only. Emails must match the full_name.",
+)
+# -> list[dict], validated and de-duplicated
+```
+
+Prefer JSON schemas? Load one and run it:
+
+```python
+from schematico import model_from_json, run_generation
+
+model, rows, instructions = model_from_json("schema.json")
+records = run_generation(model, samples=rows, instructions=instructions)
+```
+
+To find **real** data on the web instead, swap in `run_discovery` (needs
+`TAVILY_API_KEY`):
+
+```python
+from schematico import run_discovery
+records = run_discovery(User, samples=25, instructions="...")
+```
+
+Both functions accept an optional `progress_cb(found, total, event)` callback and
+a `logfire_token` for tracing.
+
+---
+
+## Bring your own models
+
+Schematico runs on [pydantic-ai](https://ai.pydantic.dev/), so you can point it
+at virtually any model — hosted, gateway-routed, or local — and even build a
+**failover chain** that tries each in order.
+
+```python
+from schematico import SchematicoModel, get_llm_model, run_discovery
+
+model = get_llm_model([
+    # try the gateway first…
+    SchematicoModel(model="gateway/anthropic:claude-sonnet-4-6"),
+    # …fall back to a direct provider…
+    SchematicoModel(model="openai:gpt-4.1", api_key="sk-..."),
+    # …then a local, keyless model.
+    SchematicoModel(model="ollama:llama3.2", base_url="http://localhost:11434/v1"),
+])
+
+records = run_discovery(MySchema, samples=50, model=model)
+```
+
+- A bare model string (`"anthropic:claude-sonnet-4-6"`) reads credentials from the
+  provider's usual env var.
+- A `SchematicoModel` lets you pin `api_key` and `base_url` per model.
+- A list becomes an automatic failover chain.
+
+From the CLI, set the model per project (`schematico new`, or
+`schematico <mode> use model <id>`) and the env var that holds its key.
+
+---
+
+## Configuration
+
+| Env var | Purpose |
+|---|---|
+| `PYDANTIC_AI_GATEWAY_API_KEY` | Key for the default gateway-routed model. |
+| `PAI_MODEL` | Override the default model id (`gateway/anthropic:claude-sonnet-4-6`). |
+| `TAVILY_API_KEY` | Required for `discover` mode (live web search). |
+| `LOGFIRE_TOKEN` | Optional. Send traces, tool calls, and token usage to [Logfire](https://pydantic.dev/logfire). |
+| `LOG_LEVEL` | `WARNING` (default), `INFO`, or `DEBUG`. |
+
+Schematico auto-loads a `.env` file from the current directory — see
+[`.env.example`](.env.example). Project configs live in `./.schematico/` as
+`<name>.<mode>.toml` files.
+
+---
+
+## Coming soon
+
+Schematico is just getting started. On the roadmap:
+
+- 📦 **More output formats** — CSV, Excel, SQL inserts, and Parquet, not just JSON.
+- 🔎 **Smarter discovery** — source citations per record, deeper crawling, and a
+  second-pass agent that verifies and de-duplicates findings.
+- 🧩 **Richer schemas** — nested objects, relationships between tables, and
+  reusable field presets.
+- 🗄️ **Direct sinks** — write straight into a database or a dataframe.
+- ⚡ **Offline generation** — a fast, keyless synthesis mode for when you don't
+  want to call a model at all.
+
+Have an idea? [Open an issue](https://github.com/Sententia-Lab/schematico/issues) —
+this is the moment to shape where it goes.
+
+---
+
+## Contributing
+
+Contributions are very welcome — issues, docs, and PRs all help. See
+[CONTRIBUTING.md](CONTRIBUTING.md) to get from clone to PR in a couple of minutes.
+The test suite mocks the LLM, so `uv run pytest` needs no API keys.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).